autoresearch
autoresearch

Validate a pipeline definition

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.

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

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/autoresearch/validate/
  • 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

target_eventstring

Event name to predict, e.g. '$pageview'. Must exist in the team's event schema. Omit when predicting an action target (pass target_definition instead).

horizon_daysinteger

Predict whether the target event occurs within this many days.

training_lookback_daysinteger

How far back to look for training examples. Default: 180.

training_populationobject

Population filter for training examples. Use {} for all identified users.

inference_populationobject

Population filter for daily scoring. When omitted or empty, the training population is counted, as creation stores it.

Example request

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

Response

Validation result with volume estimates, base rate, and warnings.

can_proceedboolean required

False when any warning has severity 'error'. Creation does not enforce it, but a definition with an 'error' 'population_too_large' or 'horizon_exceeds_lookback' cannot train.

requires_acknowledgementboolean required

True if there are non-blocking warnings the user should acknowledge before proceeding.

estimated_training_rowsinteger nullable required

Estimated number of user-level training rows based on the population and lookback window.

positive_countinteger nullable required

Estimated number of positive examples (users who performed the target event).

negative_countinteger nullable required

Estimated number of negative examples.

base_ratenumber double nullable required

Fraction of the training population that performed the target event.

inference_population_sizeinteger nullable required

Estimated number of users in the inference (daily scoring) population.

errorstring nullable required

Why validation did not run, or null when it did. A query error in the definition itself is passed through; any other failure is a generic message and the detail is logged.

Changes

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