autoresearch
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.

post/api/projects/{project_id}/autoresearch/

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/autoresearch/
  • Auth: HTTP bearer

Path parameters

project_idstring required

Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Request body

namestring required

Display name for the pipeline.

descriptionstring

Optional free-text description.

target_eventstring

PostHog event name to predict, e.g. '$pageview' or 'signed_up'. Omit when predicting an action target (pass target_definition instead).

horizon_daysinteger

Prediction horizon in days (1-365). The model predicts whether the target event occurs within this window.

training_lookback_daysinteger

How far back to look for training examples (7-730 days). Larger windows give more data but may include stale behavior. Default: 180.

training_populationobject

Training population filter. Use {} for all identified users.

inference_populationobject

Inference population filter. Defaults to training_population if not set.

cadence_daysinteger

Re-score the inference population every N days (1-365). Default: 1.

iteration_budgetinteger

Total training iterations allowed for the autoresearch loop (1-500). Default: 50.

success_aucnumber double nullable

Target AUC threshold (0-1). Training stops early if reached. Default: 0.75.

plateau_iterationsinteger

Stop training if no improvement in this many consecutive iterations (at least 1). Default: 10.

output_person_propertystring

Person property name for the prediction score, e.g. 'predicted_p_pageview'. Auto-derived from target_event if omitted. Letters, digits, and _ $ . - only, and it cannot start with $ (reserved for PostHog's own properties); must be unique among this project's non-archived pipelines.

Example request

{
  "training_population": {
    "properties": [
      {
        "key": "email",
        "type": "person",
        "operator": "is_set"
      }
    ]
  },
  "inference_population": {
    "properties": [
      {
        "key": "email",
        "type": "person",
        "operator": "is_set"
      }
    ]
  }
}

Response

idstring uuid required

Unique UUID of this pipeline.

namestring required

Display name for the pipeline.

descriptionstring

Optional free-text description.

target_eventstring required

PostHog event name to predict, e.g. '$pageview' or 'signed_up'.

horizon_daysinteger

Prediction horizon in days. The model predicts whether the target event occurs within this window.

training_lookback_daysinteger

How far back to look for training examples. Larger windows give more data but may include stale behavior.

training_populationobject required

Population used for training. Defines which users can appear as training examples.

inference_populationobject required

Population scored daily. Typically broader than the training population.

cadence_daysinteger

Re-score the inference population every N days.

iteration_budgetinteger

Total training iterations allowed for the autoresearch loop.

iteration_budget_remaininginteger required

Iterations remaining in the current budget.

success_aucnumber double nullable

Target AUC threshold. Training stops early if this score is reached.

plateau_iterationsinteger

Stop training if no AUC improvement is seen in this many consecutive iterations.

output_person_propertystring

Person property name that stores the daily prediction score, e.g. 'predicted_p_pageview'.

status'draft' | 'bootstrapping' | 'running' | 'converged' | 'paused' | 'archived' required
  • draft - Draft
  • bootstrapping - Bootstrapping
  • running - Running
  • converged - Converged
  • paused - Paused
  • archived - Archived
created_atstring date-time required
updated_atstring date-time required
last_scored_atstring date-time nullable required

Timestamp of the most recent completed inference run.

champion_holdout_aucnumber double nullable required

Offline holdout AUC of the current champion model (predictive accuracy on held-out training data).

champion_realized_aucnumber double nullable required

Realized online AUC of the current champion model, computed from mature predictions against actual outcomes.

champion_lift_at_10number double nullable required

Lift in the top 10% of scores for the current champion model, from its latest validated prediction date. 2.0 means the top 10% converts at twice the average rate.

champion_is_preliminaryboolean nullable required

True while the current champion model has no realized AUC yet. Null when the pipeline has no champion.

people_scoredinteger nullable required

People scored by the most recent completed inference run. Null before the first scoring run.

likely_countinteger nullable required

People the newest completed live run of the current champion scored at or above likely_threshold. Null before such a run, and for runs that did not record it.

likely_thresholdnumber double nullable required

The Likely cut point that likely_count used, as it was when that run scored. It is the fixed cut point until enough predictions are checked. Null when likely_count is null.

first_check_expected_atstring date-time nullable required

When online validation can first check the current champion against real outcomes: its earliest prediction date plus the horizon plus the ingestion grace. Null before the champion's first scoring run, and once a validation has checked it.

training_run_countinteger required

Training runs started for this pipeline.

experiment_countinteger required

Experiments (iterations) recorded across every training run.

Example response

{
  "training_population": {
    "properties": [
      {
        "key": "email",
        "type": "person",
        "operator": "is_set"
      }
    ]
  },
  "inference_population": {
    "properties": [
      {
        "key": "email",
        "type": "person",
        "operator": "is_set"
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.