Autoresearch

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

GET
POST
GET
GET
GET
GET
GET
POST
GET
POST
Next page →

List all autoresearch

Manage autoresearch prediction pipelines.

A pipeline defines a target event, population, and horizon. The autoresearch training loop finds the best predictive recipe; the inference workflow scores users daily and emits autoresearch_prediction events.

Required API key scopes

autoresearch:read

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/projects/:project_id/autoresearch
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "target_event": "string",
      "target_definition": {
        "type": "event"
      },
      "horizon_days": -2147483648,
      "training_lookback_days": -2147483648,
      "training_population": {
        "properties": [
          {
            "key": "email",
            "type": "person",
            "operator": "is_set"
          }
        ]
      },
      "inference_population": {
        "properties": [
          {
            "key": "email",
            "type": "person",
            "operator": "is_set"
          }
        ]
      },
      "cadence_days": -2147483648,
      "iteration_budget": -2147483648,
      "iteration_budget_remaining": 0,
      "iterations_per_run": 0,
      "research_interval_days": 7,
      "agent_model": "string",
      "agent_reasoning_effort": "string",
      "effective_agent_model": "string",
      "effective_agent_reasoning_effort": "string",
      "training_phase": "explore",
      "next_research_at": "2019-08-24T14:15:22Z",
      "success_auc": 0,
      "plateau_iterations": -2147483648,
      "output_person_property": "string",
      "write_person_property": true,
      "status": "draft",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "last_scored_at": "2019-08-24T14:15:22Z",
      "champion_holdout_auc": 0,
      "champion_realized_auc": 0,
      "champion_lift_at_10": 0,
      "champion_is_preliminary": true,
      "champion_realized_auc_trend": [
        {
          "prediction_date": "2019-08-24",
          "realized_auc": 0.1
        }
      ],
      "champion_training_trend": [
        {
          "iteration_number": 0,
          "best_holdout_score": 0.1
        }
      ],
      "people_scored": 0,
      "likely_count": 0,
      "likely_threshold": 0,
      "first_check_expected_at": "2019-08-24T14:15:22Z",
      "coverage": {
        "population": 0,
        "with_score": 0,
        "never_scored": 0,
        "age_days_avg": 0,
        "age_days_p50": 0,
        "age_days_p90": 0,
        "age_days_max": 0,
        "lookback_days": 0
      },
      "training_run_count": 0,
      "experiment_count": 0,
      "live_training_run": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "iteration_budget": 0,
        "experiment_count": 0,
        "best_holdout_score": 0,
        "latest_agent_description": "string",
        "latest_summary": "string",
        "trend": [
          {
            "iteration_number": 0,
            "best_holdout_score": 0.1
          }
        ]
      }
    }
  ]
}

List all autoresearch

Manage autoresearch prediction pipelines.

A pipeline defines a target event, population, and horizon. The autoresearch training loop finds the best predictive recipe; the inference workflow scores users daily and emits autoresearch_prediction events.

Required API key scopes

autoresearch:read

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/projects/:project_id/autoresearch
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "description": "string",
      "target_event": "string",
      "target_definition": {
        "type": "event"
      },
      "horizon_days": -2147483648,
      "training_lookback_days": -2147483648,
      "training_population": {
        "properties": [
          {
            "key": "email",
            "type": "person",
            "operator": "is_set"
          }
        ]
      },
      "inference_population": {
        "properties": [
          {
            "key": "email",
            "type": "person",
            "operator": "is_set"
          }
        ]
      },
      "cadence_days": -2147483648,
      "iteration_budget": -2147483648,
      "iteration_budget_remaining": 0,
      "iterations_per_run": 0,
      "research_interval_days": 7,
      "agent_model": "string",
      "agent_reasoning_effort": "string",
      "effective_agent_model": "string",
      "effective_agent_reasoning_effort": "string",
      "training_phase": "explore",
      "next_research_at": "2019-08-24T14:15:22Z",
      "success_auc": 0,
      "plateau_iterations": -2147483648,
      "output_person_property": "string",
      "write_person_property": true,
      "status": "draft",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "last_scored_at": "2019-08-24T14:15:22Z",
      "champion_holdout_auc": 0,
      "champion_realized_auc": 0,
      "champion_lift_at_10": 0,
      "champion_is_preliminary": true,
      "champion_realized_auc_trend": [
        {
          "prediction_date": "2019-08-24",
          "realized_auc": 0.1
        }
      ],
      "champion_training_trend": [
        {
          "iteration_number": 0,
          "best_holdout_score": 0.1
        }
      ],
      "people_scored": 0,
      "likely_count": 0,
      "likely_threshold": 0,
      "first_check_expected_at": "2019-08-24T14:15:22Z",
      "coverage": {
        "population": 0,
        "with_score": 0,
        "never_scored": 0,
        "age_days_avg": 0,
        "age_days_p50": 0,
        "age_days_p90": 0,
        "age_days_max": 0,
        "lookback_days": 0
      },
      "training_run_count": 0,
      "experiment_count": 0,
      "live_training_run": {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "iteration_budget": 0,
        "experiment_count": 0,
        "best_holdout_score": 0,
        "latest_agent_description": "string",
        "latest_summary": "string",
        "trend": [
          {
            "iteration_number": 0,
            "best_holdout_score": 0.1
          }
        ]
      }
    }
  ]
}

Create autoresearch

Manage autoresearch prediction pipelines.

A pipeline defines a target event, population, and horizon. The autoresearch training loop finds the best predictive recipe; the inference workflow scores users daily and emits autoresearch_prediction events.

Required API key scopes

autoresearch:write

Request parameters

  • name
    string
  • description
    string
  • target_event
    string
  • target_definition
  • horizon_days
    integer
  • training_lookback_days
    integer
  • training_population
    object
  • inference_population
    object
  • cadence_days
    integer
  • iteration_budget
    integer
  • iterations_per_run
    integer
  • research_interval_days
  • agent_model
    string | null
  • agent_reasoning_effort
    string | null
  • success_auc
    number | null
  • plateau_iterations
    integer
  • output_person_property
    string
  • write_person_property
    boolean

Response


Example request

POST /api/projects/:project_id/autoresearch
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/\
	-d name="string"

Example response

Status 201
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "target_event": "string",
  "target_definition": {
    "type": "event"
  },
  "horizon_days": -2147483648,
  "training_lookback_days": -2147483648,
  "training_population": {
    "properties": [
      {
        "key": "email",
        "type": "person",
        "operator": "is_set"
      }
    ]
  },
  "inference_population": {
    "properties": [
      {
        "key": "email",
        "type": "person",
        "operator": "is_set"
      }
    ]
  },
  "cadence_days": -2147483648,
  "iteration_budget": -2147483648,
  "iteration_budget_remaining": 0,
  "iterations_per_run": 0,
  "research_interval_days": 7,
  "agent_model": "string",
  "agent_reasoning_effort": "string",
  "effective_agent_model": "string",
  "effective_agent_reasoning_effort": "string",
  "training_phase": "explore",
  "next_research_at": "2019-08-24T14:15:22Z",
  "success_auc": 0,
  "plateau_iterations": -2147483648,
  "output_person_property": "string",
  "write_person_property": true,
  "status": "draft",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "last_scored_at": "2019-08-24T14:15:22Z",
  "champion_holdout_auc": 0,
  "champion_realized_auc": 0,
  "champion_lift_at_10": 0,
  "champion_is_preliminary": true,
  "champion_realized_auc_trend": [
    {
      "prediction_date": "2019-08-24",
      "realized_auc": 0.1
    }
  ],
  "champion_training_trend": [
    {
      "iteration_number": 0,
      "best_holdout_score": 0.1
    }
  ],
  "people_scored": 0,
  "likely_count": 0,
  "likely_threshold": 0,
  "first_check_expected_at": "2019-08-24T14:15:22Z",
  "coverage": {
    "population": 0,
    "with_score": 0,
    "never_scored": 0,
    "age_days_avg": 0,
    "age_days_p50": 0,
    "age_days_p90": 0,
    "age_days_max": 0,
    "lookback_days": 0
  },
  "training_run_count": 0,
  "experiment_count": 0,
  "live_training_run": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "iteration_budget": 0,
    "experiment_count": 0,
    "best_holdout_score": 0,
    "latest_agent_description": "string",
    "latest_summary": "string",
    "trend": [
      {
        "iteration_number": 0,
        "best_holdout_score": 0.1
      }
    ]
  }
}

Create autoresearch

Manage autoresearch prediction pipelines.

A pipeline defines a target event, population, and horizon. The autoresearch training loop finds the best predictive recipe; the inference workflow scores users daily and emits autoresearch_prediction events.

Required API key scopes

autoresearch:write

Request parameters

  • name
    string
  • description
    string
  • target_event
    string
  • target_definition
  • horizon_days
    integer
  • training_lookback_days
    integer
  • training_population
    object
  • inference_population
    object
  • cadence_days
    integer
  • iteration_budget
    integer
  • iterations_per_run
    integer
  • research_interval_days
  • agent_model
    string | null
  • agent_reasoning_effort
    string | null
  • success_auc
    number | null
  • plateau_iterations
    integer
  • output_person_property
    string
  • write_person_property
    boolean

Response


Example request

POST /api/projects/:project_id/autoresearch
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/\
	-d name="string"

Example response

Status 201
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "description": "string",
  "target_event": "string",
  "target_definition": {
    "type": "event"
  },
  "horizon_days": -2147483648,
  "training_lookback_days": -2147483648,
  "training_population": {
    "properties": [
      {
        "key": "email",
        "type": "person",
        "operator": "is_set"
      }
    ]
  },
  "inference_population": {
    "properties": [
      {
        "key": "email",
        "type": "person",
        "operator": "is_set"
      }
    ]
  },
  "cadence_days": -2147483648,
  "iteration_budget": -2147483648,
  "iteration_budget_remaining": 0,
  "iterations_per_run": 0,
  "research_interval_days": 7,
  "agent_model": "string",
  "agent_reasoning_effort": "string",
  "effective_agent_model": "string",
  "effective_agent_reasoning_effort": "string",
  "training_phase": "explore",
  "next_research_at": "2019-08-24T14:15:22Z",
  "success_auc": 0,
  "plateau_iterations": -2147483648,
  "output_person_property": "string",
  "write_person_property": true,
  "status": "draft",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "last_scored_at": "2019-08-24T14:15:22Z",
  "champion_holdout_auc": 0,
  "champion_realized_auc": 0,
  "champion_lift_at_10": 0,
  "champion_is_preliminary": true,
  "champion_realized_auc_trend": [
    {
      "prediction_date": "2019-08-24",
      "realized_auc": 0.1
    }
  ],
  "champion_training_trend": [
    {
      "iteration_number": 0,
      "best_holdout_score": 0.1
    }
  ],
  "people_scored": 0,
  "likely_count": 0,
  "likely_threshold": 0,
  "first_check_expected_at": "2019-08-24T14:15:22Z",
  "coverage": {
    "population": 0,
    "with_score": 0,
    "never_scored": 0,
    "age_days_avg": 0,
    "age_days_p50": 0,
    "age_days_p90": 0,
    "age_days_max": 0,
    "lookback_days": 0
  },
  "training_run_count": 0,
  "experiment_count": 0,
  "live_training_run": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "iteration_budget": 0,
    "experiment_count": 0,
    "best_holdout_score": 0,
    "latest_agent_description": "string",
    "latest_summary": "string",
    "trend": [
      {
        "iteration_number": 0,
        "best_holdout_score": 0.1
      }
    ]
  }
}

List all autoresearch models

List and retrieve champion/challenger models for a pipeline.

Models are the persisted artifacts produced by training runs. Each model holds a portable recipe (feature SQL, transforms, model class, params) that the daily inference workflow compiles to score users.

Required API key scopes

autoresearch:read

Path parameters

  • pipeline_id
    string

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/projects/:project_id/autoresearch/:pipeline_id/models
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/models/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
      "role": "champion",
      "recipe_hash": "string",
      "model_recipe": {
        "feature_sql": "SELECT a.person_id AS distinct_id, countIf(e.event='$pageview') AS pageviews_30d FROM {anchors} a LEFT JOIN events e ON e.person_id = a.person_id AND e.timestamp < fromUnixTimestamp(a.cutoff_ts) GROUP BY a.person_id",
        "feature_transforms": [],
        "model_class": "sklearn.linear_model.LogisticRegression",
        "model_params": {
          "C": 1,
          "max_iter": 200
        },
        "fit_signature": "abc123",
        "trained_on": "2026-04-01 to 2026-05-01",
        "holdout_score": 0.72,
        "agent_description": "Stub recipe: universal engagement features"
      },
      "model_explanation": {
        "top_features": [
          {
            "name": "string",
            "importance": 0.1,
            "direction": "positive"
          }
        ],
        "method": "string",
        "note": "string"
      },
      "holdout_score": 0,
      "realized_score": 0,
      "calibration_error": 0,
      "metrics": {},
      "source_training_run": "3e133df1-d77e-44e9-acf1-2d742abab9db",
      "agent_description": "string",
      "trained_on_start": "2019-08-24",
      "trained_on_end": "2019-08-24",
      "is_preliminary": true,
      "promoted_at": "2019-08-24T14:15:22Z",
      "archived_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "in_shadow_set": true
    }
  ]
}

List all autoresearch models

List and retrieve champion/challenger models for a pipeline.

Models are the persisted artifacts produced by training runs. Each model holds a portable recipe (feature SQL, transforms, model class, params) that the daily inference workflow compiles to score users.

Required API key scopes

autoresearch:read

Path parameters

  • pipeline_id
    string

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/projects/:project_id/autoresearch/:pipeline_id/models
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/models/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
      "role": "champion",
      "recipe_hash": "string",
      "model_recipe": {
        "feature_sql": "SELECT a.person_id AS distinct_id, countIf(e.event='$pageview') AS pageviews_30d FROM {anchors} a LEFT JOIN events e ON e.person_id = a.person_id AND e.timestamp < fromUnixTimestamp(a.cutoff_ts) GROUP BY a.person_id",
        "feature_transforms": [],
        "model_class": "sklearn.linear_model.LogisticRegression",
        "model_params": {
          "C": 1,
          "max_iter": 200
        },
        "fit_signature": "abc123",
        "trained_on": "2026-04-01 to 2026-05-01",
        "holdout_score": 0.72,
        "agent_description": "Stub recipe: universal engagement features"
      },
      "model_explanation": {
        "top_features": [
          {
            "name": "string",
            "importance": 0.1,
            "direction": "positive"
          }
        ],
        "method": "string",
        "note": "string"
      },
      "holdout_score": 0,
      "realized_score": 0,
      "calibration_error": 0,
      "metrics": {},
      "source_training_run": "3e133df1-d77e-44e9-acf1-2d742abab9db",
      "agent_description": "string",
      "trained_on_start": "2019-08-24",
      "trained_on_end": "2019-08-24",
      "is_preliminary": true,
      "promoted_at": "2019-08-24T14:15:22Z",
      "archived_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "in_shadow_set": true
    }
  ]
}

Retrieve autoresearch models

List and retrieve champion/challenger models for a pipeline.

Models are the persisted artifacts produced by training runs. Each model holds a portable recipe (feature SQL, transforms, model class, params) that the daily inference workflow compiles to score users.

Required API key scopes

autoresearch:read

Path parameters

  • id
    string
  • pipeline_id
    string

Response


Example request

GET /api/projects/:project_id/autoresearch/:pipeline_id/models/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/models/:id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
  "role": "champion",
  "recipe_hash": "string",
  "model_recipe": {
    "feature_sql": "SELECT a.person_id AS distinct_id, countIf(e.event='$pageview') AS pageviews_30d FROM {anchors} a LEFT JOIN events e ON e.person_id = a.person_id AND e.timestamp < fromUnixTimestamp(a.cutoff_ts) GROUP BY a.person_id",
    "feature_transforms": [],
    "model_class": "sklearn.linear_model.LogisticRegression",
    "model_params": {
      "C": 1,
      "max_iter": 200
    },
    "fit_signature": "abc123",
    "trained_on": "2026-04-01 to 2026-05-01",
    "holdout_score": 0.72,
    "agent_description": "Stub recipe: universal engagement features"
  },
  "model_explanation": {
    "top_features": [
      {
        "name": "string",
        "importance": 0.1,
        "direction": "positive"
      }
    ],
    "method": "string",
    "note": "string"
  },
  "holdout_score": 0,
  "realized_score": 0,
  "calibration_error": 0,
  "metrics": {},
  "source_training_run": "3e133df1-d77e-44e9-acf1-2d742abab9db",
  "agent_description": "string",
  "trained_on_start": "2019-08-24",
  "trained_on_end": "2019-08-24",
  "is_preliminary": true,
  "promoted_at": "2019-08-24T14:15:22Z",
  "archived_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "in_shadow_set": true
}

Retrieve autoresearch models

List and retrieve champion/challenger models for a pipeline.

Models are the persisted artifacts produced by training runs. Each model holds a portable recipe (feature SQL, transforms, model class, params) that the daily inference workflow compiles to score users.

Required API key scopes

autoresearch:read

Path parameters

  • id
    string
  • pipeline_id
    string

Response


Example request

GET /api/projects/:project_id/autoresearch/:pipeline_id/models/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/models/:id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
  "role": "champion",
  "recipe_hash": "string",
  "model_recipe": {
    "feature_sql": "SELECT a.person_id AS distinct_id, countIf(e.event='$pageview') AS pageviews_30d FROM {anchors} a LEFT JOIN events e ON e.person_id = a.person_id AND e.timestamp < fromUnixTimestamp(a.cutoff_ts) GROUP BY a.person_id",
    "feature_transforms": [],
    "model_class": "sklearn.linear_model.LogisticRegression",
    "model_params": {
      "C": 1,
      "max_iter": 200
    },
    "fit_signature": "abc123",
    "trained_on": "2026-04-01 to 2026-05-01",
    "holdout_score": 0.72,
    "agent_description": "Stub recipe: universal engagement features"
  },
  "model_explanation": {
    "top_features": [
      {
        "name": "string",
        "importance": 0.1,
        "direction": "positive"
      }
    ],
    "method": "string",
    "note": "string"
  },
  "holdout_score": 0,
  "realized_score": 0,
  "calibration_error": 0,
  "metrics": {},
  "source_training_run": "3e133df1-d77e-44e9-acf1-2d742abab9db",
  "agent_description": "string",
  "trained_on_start": "2019-08-24",
  "trained_on_end": "2019-08-24",
  "is_preliminary": true,
  "promoted_at": "2019-08-24T14:15:22Z",
  "archived_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "in_shadow_set": true
}

List all autoresearch runs

List and retrieve inference and validation runs for a pipeline.

Required API key scopes

autoresearch:read

Path parameters

  • pipeline_id
    string

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/projects/:project_id/autoresearch/:pipeline_id/runs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/runs/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
      "model": "a047ecae-0f27-4ff4-95bb-0f06d1225aa8",
      "run_type": "inference",
      "status": "pending",
      "rows_scored": -2147483648,
      "metrics": {},
      "coverage": {
        "population": 0,
        "with_score": 0,
        "never_scored": 0,
        "age_days_avg": 0,
        "age_days_p50": 0,
        "age_days_p90": 0,
        "age_days_max": 0,
        "lookback_days": 0
      },
      "error": "string",
      "started_at": "2019-08-24T14:15:22Z",
      "completed_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ]
}

List all autoresearch runs

List and retrieve inference and validation runs for a pipeline.

Required API key scopes

autoresearch:read

Path parameters

  • pipeline_id
    string

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/projects/:project_id/autoresearch/:pipeline_id/runs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/runs/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
      "model": "a047ecae-0f27-4ff4-95bb-0f06d1225aa8",
      "run_type": "inference",
      "status": "pending",
      "rows_scored": -2147483648,
      "metrics": {},
      "coverage": {
        "population": 0,
        "with_score": 0,
        "never_scored": 0,
        "age_days_avg": 0,
        "age_days_p50": 0,
        "age_days_p90": 0,
        "age_days_max": 0,
        "lookback_days": 0
      },
      "error": "string",
      "started_at": "2019-08-24T14:15:22Z",
      "completed_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Retrieve autoresearch runs

List and retrieve inference and validation runs for a pipeline.

Required API key scopes

autoresearch:read

Path parameters

  • id
    string
  • pipeline_id
    string

Response


Example request

GET /api/projects/:project_id/autoresearch/:pipeline_id/runs/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/runs/:id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
  "model": "a047ecae-0f27-4ff4-95bb-0f06d1225aa8",
  "run_type": "inference",
  "status": "pending",
  "rows_scored": -2147483648,
  "metrics": {},
  "coverage": {
    "population": 0,
    "with_score": 0,
    "never_scored": 0,
    "age_days_avg": 0,
    "age_days_p50": 0,
    "age_days_p90": 0,
    "age_days_max": 0,
    "lookback_days": 0
  },
  "error": "string",
  "started_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z"
}

Retrieve autoresearch runs

List and retrieve inference and validation runs for a pipeline.

Required API key scopes

autoresearch:read

Path parameters

  • id
    string
  • pipeline_id
    string

Response


Example request

GET /api/projects/:project_id/autoresearch/:pipeline_id/runs/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/runs/:id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
  "model": "a047ecae-0f27-4ff4-95bb-0f06d1225aa8",
  "run_type": "inference",
  "status": "pending",
  "rows_scored": -2147483648,
  "metrics": {},
  "coverage": {
    "population": 0,
    "with_score": 0,
    "never_scored": 0,
    "age_days_avg": 0,
    "age_days_p50": 0,
    "age_days_p90": 0,
    "age_days_max": 0,
    "lookback_days": 0
  },
  "error": "string",
  "started_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z"
}

List all autoresearch suggestions

List steering suggestions for a pipeline, ordered most recent first. Check 'status' to see which have been picked up or acted on by the agent.

Required API key scopes

autoresearch:read

Path parameters

  • pipeline_id
    string

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/projects/:project_id/autoresearch/:pipeline_id/suggestions
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/suggestions/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
      "prompt": "string",
      "priority": "try_next",
      "status": "queued",
      "source": "user",
      "agent_response": "string",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "linked_iteration_ids": [
        "497f6eca-6276-4993-bfeb-53cbbbba6f08"
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}

List all autoresearch suggestions

List steering suggestions for a pipeline, ordered most recent first. Check 'status' to see which have been picked up or acted on by the agent.

Required API key scopes

autoresearch:read

Path parameters

  • pipeline_id
    string

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/projects/:project_id/autoresearch/:pipeline_id/suggestions
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/suggestions/

Example response

Status 200
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
      "prompt": "string",
      "priority": "try_next",
      "status": "queued",
      "source": "user",
      "agent_response": "string",
      "created_by": {
        "id": 0,
        "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
        "distinct_id": "string",
        "first_name": "string",
        "last_name": "string",
        "email": "user@example.com",
        "is_email_verified": true,
        "hedgehog_config": {},
        "role_at_organization": "engineering"
      },
      "linked_iteration_ids": [
        "497f6eca-6276-4993-bfeb-53cbbbba6f08"
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create autoresearch suggestions

Inject a free-text hypothesis or direction into a running pipeline. The sandbox agent reads queued suggestions at the start of each iteration batch and decides: translate into a concrete iteration ('acted_on'), apply as a search constraint ('picked_up'), or reject with rationale ('dismissed'). Use priority='try_next' to instruct the agent to act on this before autonomous iterations; 'consider' is advisory. Check 'agent_response' after the next training run to see how the suggestion was interpreted.

Required API key scopes

autoresearch:write

Path parameters

  • pipeline_id
    string

Request parameters

  • prompt
    string
  • priority
    Default: consider

Response


Example request

POST /api/projects/:project_id/autoresearch/:pipeline_id/suggestions
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/suggestions/\
	-d prompt="string"

Example response

Status 201 The created suggestion. The agent will pick it up at the start of the next training batch.
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
  "prompt": "string",
  "priority": "try_next",
  "status": "queued",
  "source": "user",
  "agent_response": "string",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "linked_iteration_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Create autoresearch suggestions

Inject a free-text hypothesis or direction into a running pipeline. The sandbox agent reads queued suggestions at the start of each iteration batch and decides: translate into a concrete iteration ('acted_on'), apply as a search constraint ('picked_up'), or reject with rationale ('dismissed'). Use priority='try_next' to instruct the agent to act on this before autonomous iterations; 'consider' is advisory. Check 'agent_response' after the next training run to see how the suggestion was interpreted.

Required API key scopes

autoresearch:write

Path parameters

  • pipeline_id
    string

Request parameters

  • prompt
    string
  • priority
    Default: consider

Response


Example request

POST /api/projects/:project_id/autoresearch/:pipeline_id/suggestions
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/suggestions/\
	-d prompt="string"

Example response

Status 201 The created suggestion. The agent will pick it up at the start of the next training batch.
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
  "prompt": "string",
  "priority": "try_next",
  "status": "queued",
  "source": "user",
  "agent_response": "string",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "linked_iteration_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Retrieve autoresearch suggestions

Get details for a specific suggestion including its status and agent_response.

Required API key scopes

autoresearch:read

Path parameters

  • id
    string
  • pipeline_id
    string

Response


Example request

GET /api/projects/:project_id/autoresearch/:pipeline_id/suggestions/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/suggestions/:id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
  "prompt": "string",
  "priority": "try_next",
  "status": "queued",
  "source": "user",
  "agent_response": "string",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "linked_iteration_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Retrieve autoresearch suggestions

Get details for a specific suggestion including its status and agent_response.

Required API key scopes

autoresearch:read

Path parameters

  • id
    string
  • pipeline_id
    string

Response


Example request

GET /api/projects/:project_id/autoresearch/:pipeline_id/suggestions/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/suggestions/:id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
  "prompt": "string",
  "priority": "try_next",
  "status": "queued",
  "source": "user",
  "agent_response": "string",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "linked_iteration_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}

Create autoresearch suggestions respond

Record how the agent handled a steering suggestion: set status to 'picked_up' (applied as a search constraint), 'acted_on' (spawned iterations), or 'dismissed' (rejected — explain in agent_response), and write the agent_response note the human will read. Call this from the training loop after deciding what to do with a pending suggestion. Recording an iteration with parent_suggestion set already advances a suggestion to 'acted_on'; use this to add the narrative or to mark a suggestion picked_up/dismissed without spawning an iteration. A suggestion only moves forward (queued, picked_up, then acted_on or dismissed); the same status again updates the note.

Required API key scopes

autoresearch:write

Path parameters

  • id
    string
  • pipeline_id
    string

Request parameters

  • status
  • agent_response
    string

Response


Example request

POST /api/projects/:project_id/autoresearch/:pipeline_id/suggestions/:id/respond
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/suggestions/:id/respond/\
	-d status=undefined

Example response

Status 200 The updated suggestion with its new status and agent_response.
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
  "prompt": "string",
  "priority": "try_next",
  "status": "queued",
  "source": "user",
  "agent_response": "string",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "linked_iteration_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}
Status 400 The status would move the suggestion backwards, acted_on has no linked iteration, a dismissal has no explanation, or the pipeline is archived.

Create autoresearch suggestions respond

Record how the agent handled a steering suggestion: set status to 'picked_up' (applied as a search constraint), 'acted_on' (spawned iterations), or 'dismissed' (rejected — explain in agent_response), and write the agent_response note the human will read. Call this from the training loop after deciding what to do with a pending suggestion. Recording an iteration with parent_suggestion set already advances a suggestion to 'acted_on'; use this to add the narrative or to mark a suggestion picked_up/dismissed without spawning an iteration. A suggestion only moves forward (queued, picked_up, then acted_on or dismissed); the same status again updates the note.

Required API key scopes

autoresearch:write

Path parameters

  • id
    string
  • pipeline_id
    string

Request parameters

  • status
  • agent_response
    string

Response


Example request

POST /api/projects/:project_id/autoresearch/:pipeline_id/suggestions/:id/respond
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/autoresearch/:pipeline_id/suggestions/:id/respond/\
	-d status=undefined

Example response

Status 200 The updated suggestion with its new status and agent_response.
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
  "prompt": "string",
  "priority": "try_next",
  "status": "queued",
  "source": "user",
  "agent_response": "string",
  "created_by": {
    "id": 0,
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
    "distinct_id": "string",
    "first_name": "string",
    "last_name": "string",
    "email": "user@example.com",
    "is_email_verified": true,
    "hedgehog_config": {},
    "role_at_organization": "engineering"
  },
  "linked_iteration_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z"
}
Status 400 The status would move the suggestion backwards, acted_on has no linked iteration, a dismissal has no explanation, or the pipeline is archived.
Next page →