Autoresearch

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

Endpoints

POST
POST
GET
POST
GET
POST
← Previous page

Create autoresearch train

Start an asynchronous training run for this pipeline. Creates a Task/TaskRun sandbox where the autoresearch agent iterates on features and models, and returns the run immediately with status 'running'. Poll the training run until it reaches a terminal status (completed or failed). A pipeline's first run has no champion until it completes and promotion runs; on a retrain the existing champion stays live and keeps scoring until a new one is promoted.

Required API key scopes

autoresearch:writequery:readinsight:read

Path parameters

  • id
    string

Request parameters

  • iteration_budget
    integer

Response


Example request

POST /api/projects/:project_id/autoresearch/:id/train
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/:id/train/\
	-d iteration_budget="integer"

Example response

Status 200 The created training run. Poll it through the training runs endpoint.
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b",
  "task_url": "string",
  "status": "pending",
  "kickoff_reason": "explore",
  "agent_runtime_adapter": "string",
  "agent_model": "string",
  "agent_model_label": "string",
  "agent_reasoning_effort": "string",
  "iteration_budget": -2147483648,
  "iteration_count": 0,
  "best_holdout_score": 0,
  "summary": {
    "target_event": "string",
    "horizon_days": 0,
    "best_holdout_score": 0,
    "champion_promoted": true,
    "champion_model_class": "string",
    "kept_ladder": [
      {
        "iteration_number": 0,
        "holdout_score": 0,
        "model_class": "string",
        "agent_description": "string"
      }
    ],
    "dead_ends": [
      {
        "iteration_number": 0,
        "holdout_score": 0,
        "model_class": "string",
        "agent_description": "string"
      }
    ],
    "recommended_next": "string",
    "distillation": "string",
    "report_notebook_short_id": ""
  },
  "reader_summary": "string",
  "headline": "string",
  "next_steps": [
    "string"
  ],
  "iterations": [
    {
      "iteration_number": -2147483648,
      "status": "kept",
      "holdout_score": 0,
      "train_score": 0,
      "agent_description": "string",
      "summary": "string",
      "headline": "string",
      "model_spec": {
        "model_class": "sklearn.linear_model.LogisticRegression",
        "model_params": {
          "C": 1
        }
      }
    }
  ],
  "error": "string",
  "started_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z"
}
Status 400 A training run is already in progress, the pipeline is paused, or the pipeline's target or creator is no longer valid.
Status 403 The caller has no PostHog Desktop access, which cloud runs need, or the request comes from inside a sandbox.
Status 404 The pipeline does not exist or is archived.
Status 429 The team is over its PostHog Desktop usage limit.
Status 503 PostHog Desktop access could not be checked. Try again.

Create autoresearch train

Start an asynchronous training run for this pipeline. Creates a Task/TaskRun sandbox where the autoresearch agent iterates on features and models, and returns the run immediately with status 'running'. Poll the training run until it reaches a terminal status (completed or failed). A pipeline's first run has no champion until it completes and promotion runs; on a retrain the existing champion stays live and keeps scoring until a new one is promoted.

Required API key scopes

autoresearch:writequery:readinsight:read

Path parameters

  • id
    string

Request parameters

  • iteration_budget
    integer

Response


Example request

POST /api/projects/:project_id/autoresearch/:id/train
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/:id/train/\
	-d iteration_budget="integer"

Example response

Status 200 The created training run. Poll it through the training runs endpoint.
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "pipeline": "84876997-3a84-47a2-8c28-237e28b9b816",
  "task_id": "736fde4d-9029-4915-8189-01353d6982cb",
  "task_run_id": "7f0ef9d7-e7b5-4d52-8247-ce8351652f8b",
  "task_url": "string",
  "status": "pending",
  "kickoff_reason": "explore",
  "agent_runtime_adapter": "string",
  "agent_model": "string",
  "agent_model_label": "string",
  "agent_reasoning_effort": "string",
  "iteration_budget": -2147483648,
  "iteration_count": 0,
  "best_holdout_score": 0,
  "summary": {
    "target_event": "string",
    "horizon_days": 0,
    "best_holdout_score": 0,
    "champion_promoted": true,
    "champion_model_class": "string",
    "kept_ladder": [
      {
        "iteration_number": 0,
        "holdout_score": 0,
        "model_class": "string",
        "agent_description": "string"
      }
    ],
    "dead_ends": [
      {
        "iteration_number": 0,
        "holdout_score": 0,
        "model_class": "string",
        "agent_description": "string"
      }
    ],
    "recommended_next": "string",
    "distillation": "string",
    "report_notebook_short_id": ""
  },
  "reader_summary": "string",
  "headline": "string",
  "next_steps": [
    "string"
  ],
  "iterations": [
    {
      "iteration_number": -2147483648,
      "status": "kept",
      "holdout_score": 0,
      "train_score": 0,
      "agent_description": "string",
      "summary": "string",
      "headline": "string",
      "model_spec": {
        "model_class": "sklearn.linear_model.LogisticRegression",
        "model_params": {
          "C": 1
        }
      }
    }
  ],
  "error": "string",
  "started_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z",
  "created_at": "2019-08-24T14:15:22Z"
}
Status 400 A training run is already in progress, the pipeline is paused, or the pipeline's target or creator is no longer valid.
Status 403 The caller has no PostHog Desktop access, which cloud runs need, or the request comes from inside a sandbox.
Status 404 The pipeline does not exist or is archived.
Status 429 The team is over its PostHog Desktop usage limit.
Status 503 PostHog Desktop access could not be checked. Try again.

Create autoresearch validate online

Validate predictions against realized outcomes for all matured prediction dates. A prediction date is matured when today >= prediction_date + horizon_days. Computes realized AUC, Brier score, calibration error (ECE), and lift@10/20 per model. Updates the model's realized_score, calibration_error, and clears the is_preliminary flag. Already-validated dates are skipped. In production this is triggered by the daily Temporal validation workflow after inference runs.

Required API key scopes

autoresearch:writequery:read

Path parameters

  • id
    string

Example request

POST /api/projects/:project_id/autoresearch/:id/validate_online
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/:id/validate_online/

Example response

Status 200 One AutoresearchRun per matured prediction date that was validated. Empty list when no prediction dates have matured yet.
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"
}
Status 400 An action target needs the action:read scope.
Status 404 The pipeline does not exist or is archived.

Create autoresearch validate online

Validate predictions against realized outcomes for all matured prediction dates. A prediction date is matured when today >= prediction_date + horizon_days. Computes realized AUC, Brier score, calibration error (ECE), and lift@10/20 per model. Updates the model's realized_score, calibration_error, and clears the is_preliminary flag. Already-validated dates are skipped. In production this is triggered by the daily Temporal validation workflow after inference runs.

Required API key scopes

autoresearch:writequery:read

Path parameters

  • id
    string

Example request

POST /api/projects/:project_id/autoresearch/:id/validate_online
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/:id/validate_online/

Example response

Status 200 One AutoresearchRun per matured prediction date that was validated. Empty list when no prediction dates have matured yet.
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"
}
Status 400 An action target needs the action:read scope.
Status 404 The pipeline does not exist or is archived.

Retrieve autoresearch agent models

Return the models a pipeline's training agent may run on, with the reasoning efforts each supports and its relative token cost, plus the model and effort a pipeline with blank settings uses. Pass a model id as agent_model and an effort as agent_reasoning_effort on create or update.

Required API key scopes

autoresearch:read

Response


Example request

GET /api/projects/:project_id/autoresearch/agent_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/agent_models/

Example response

Status 200
RESPONSE
{
  "default_model": "string",
  "default_model_label": "string",
  "default_reasoning_effort": "string",
  "models": [
    {
      "model": "string",
      "label": "string",
      "runtime_adapter": "string",
      "supported_efforts": [
        {
          "value": "string",
          "label": "string"
        }
      ],
      "cost_multiplier": "string"
    }
  ]
}

Retrieve autoresearch agent models

Return the models a pipeline's training agent may run on, with the reasoning efforts each supports and its relative token cost, plus the model and effort a pipeline with blank settings uses. Pass a model id as agent_model and an effort as agent_reasoning_effort on create or update.

Required API key scopes

autoresearch:read

Response


Example request

GET /api/projects/:project_id/autoresearch/agent_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/agent_models/

Example response

Status 200
RESPONSE
{
  "default_model": "string",
  "default_model_label": "string",
  "default_reasoning_effort": "string",
  "models": [
    {
      "model": "string",
      "label": "string",
      "runtime_adapter": "string",
      "supported_efforts": [
        {
          "value": "string",
          "label": "string"
        }
      ],
      "cost_multiplier": "string"
    }
  ]
}

Create autoresearch resolve template

Resolve a template key and optional overrides into a concrete pipeline config. For activity-based templates ('likely_active_soon', 'at_risk_of_inactivity', 'return_after_first_use'), the target event is auto-resolved from your event schema — check resolved_activity_event and activity_event_alternatives, then override if needed. For 'feature_adoption' and 'repeat_key_behavior', supply target_event. After resolving, call autoresearch-validate-create to check volume and warnings, then autoresearch-create to create the pipeline.

Required API key scopes

autoresearch:readquery:read

Request parameters

  • template_key
  • target_event
    string
  • horizon_days
    integer

Response


Example request

POST /api/projects/:project_id/autoresearch/resolve-template
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/resolve-template/\
	-d template_key=undefined

Example response

Status 200 Resolved pipeline config. Pass target_event, horizon_days, training_lookback_days, training_population, inference_population, and output_person_property directly to autoresearch-create. Always run autoresearch-validate-create on the resolved config before creating.
RESPONSE
{
  "template_key": "likely_active_soon",
  "display_name": "string",
  "description": "string",
  "suggested_name": "string",
  "target_event": "string",
  "resolved_activity_event": "string",
  "activity_event_alternatives": [
    "string"
  ],
  "horizon_days": 0,
  "training_lookback_days": 0,
  "training_population": {
    "kind": "performed_event_within_days",
    "event": "$pageview",
    "days": 30
  },
  "inference_population": {
    "kind": "performed_event_within_days",
    "event": "$pageview",
    "days": 30
  },
  "output_person_property": "string",
  "notes": "string"
}
Status 400 Unknown template key or missing required target_event override.

Create autoresearch resolve template

Resolve a template key and optional overrides into a concrete pipeline config. For activity-based templates ('likely_active_soon', 'at_risk_of_inactivity', 'return_after_first_use'), the target event is auto-resolved from your event schema — check resolved_activity_event and activity_event_alternatives, then override if needed. For 'feature_adoption' and 'repeat_key_behavior', supply target_event. After resolving, call autoresearch-validate-create to check volume and warnings, then autoresearch-create to create the pipeline.

Required API key scopes

autoresearch:readquery:read

Request parameters

  • template_key
  • target_event
    string
  • horizon_days
    integer

Response


Example request

POST /api/projects/:project_id/autoresearch/resolve-template
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/resolve-template/\
	-d template_key=undefined

Example response

Status 200 Resolved pipeline config. Pass target_event, horizon_days, training_lookback_days, training_population, inference_population, and output_person_property directly to autoresearch-create. Always run autoresearch-validate-create on the resolved config before creating.
RESPONSE
{
  "template_key": "likely_active_soon",
  "display_name": "string",
  "description": "string",
  "suggested_name": "string",
  "target_event": "string",
  "resolved_activity_event": "string",
  "activity_event_alternatives": [
    "string"
  ],
  "horizon_days": 0,
  "training_lookback_days": 0,
  "training_population": {
    "kind": "performed_event_within_days",
    "event": "$pageview",
    "days": 30
  },
  "inference_population": {
    "kind": "performed_event_within_days",
    "event": "$pageview",
    "days": 30
  },
  "output_person_property": "string",
  "notes": "string"
}
Status 400 Unknown template key or missing required target_event override.

List all autoresearch templates

Return all built-in autoresearch prediction templates. Each entry describes what the template predicts, its default horizon and prediction mode, and whether it requires you to supply a target_event. After choosing a template, call autoresearch-resolve-template-create to get a fully resolved pipeline config ready to pass to autoresearch-create.

Required API key scopes

autoresearch:read

Example request

GET /api/projects/:project_id/autoresearch/templates
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/templates/

Example response

Status 200
RESPONSE
{
  "key": "likely_active_soon",
  "display_name": "string",
  "description": "string",
  "default_horizon_days": 0,
  "requires_user_event": true,
  "requires_activity_resolution": true,
  "notes": "string"
}

List all autoresearch templates

Return all built-in autoresearch prediction templates. Each entry describes what the template predicts, its default horizon and prediction mode, and whether it requires you to supply a target_event. After choosing a template, call autoresearch-resolve-template-create to get a fully resolved pipeline config ready to pass to autoresearch-create.

Required API key scopes

autoresearch:read

Example request

GET /api/projects/:project_id/autoresearch/templates
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/templates/

Example response

Status 200
RESPONSE
{
  "key": "likely_active_soon",
  "display_name": "string",
  "description": "string",
  "default_horizon_days": 0,
  "requires_user_event": true,
  "requires_activity_resolution": true,
  "notes": "string"
}

Create autoresearch validate

Validate a proposed pipeline's target event and population before creating it. Returns volume estimates, base rate, and any warnings. Creation does not enforce the result: 'horizon_exceeds_lookback' and an 'error' 'population_too_large' mean a run would fail, and the other 'error' codes mean the data is too thin for a reliable model. Call this before autoresearch-create.

Required API key scopes

autoresearch:readquery:read

Request parameters

  • target_event
    string
    Default:
  • target_definition
  • horizon_days
    integer
    Default: 7
  • training_lookback_days
    integer
    Default: 180
  • training_population
    object
  • inference_population
    object

Response


Example request

POST /api/projects/:project_id/autoresearch/validate
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/validate/\
	-d target_event="string"

Example response

Status 200 Validation result with volume estimates, base rate, and warnings.
RESPONSE
{
  "can_proceed": true,
  "requires_acknowledgement": true,
  "estimated_training_rows": 0,
  "positive_count": 0,
  "negative_count": 0,
  "base_rate": 0,
  "inference_population_size": 0,
  "warnings": [
    {
      "code": "string",
      "message": "string",
      "severity": "info"
    }
  ],
  "error": "string"
}

Create autoresearch validate

Validate a proposed pipeline's target event and population before creating it. Returns volume estimates, base rate, and any warnings. Creation does not enforce the result: 'horizon_exceeds_lookback' and an 'error' 'population_too_large' mean a run would fail, and the other 'error' codes mean the data is too thin for a reliable model. Call this before autoresearch-create.

Required API key scopes

autoresearch:readquery:read

Request parameters

  • target_event
    string
    Default:
  • target_definition
  • horizon_days
    integer
    Default: 7
  • training_lookback_days
    integer
    Default: 180
  • training_population
    object
  • inference_population
    object

Response


Example request

POST /api/projects/:project_id/autoresearch/validate
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/validate/\
	-d target_event="string"

Example response

Status 200 Validation result with volume estimates, base rate, and warnings.
RESPONSE
{
  "can_proceed": true,
  "requires_acknowledgement": true,
  "estimated_training_rows": 0,
  "positive_count": 0,
  "negative_count": 0,
  "base_rate": 0,
  "inference_population_size": 0,
  "warnings": [
    {
      "code": "string",
      "message": "string",
      "severity": "info"
    }
  ],
  "error": "string"
}
← Previous page