/working-with-autoresearch

name: working-with-autoresearch
description: >
  Use PostHog Autoresearch, agent-driven predictive models: ask "who will do X in the next N days?",
  let an agent train a model, then score people daily into a person property and
  `autoresearch_prediction` events. Use when a user wants to predict churn, activity, return,
  feature adoption, conversion or any event or action per person; create or validate a model from a
  template; start training or score now; read model quality (holdout vs realized AUC, lift,
  calibration, likelihood segments, coverage); steer training with suggestions; act on predictions
  with cohorts, feature flags, workflows or SQL; or diagnose a model that fails to train, scores
  everyone the same, or stops scoring. Trigger on "autoresearch", "predictive model", "propensity
  score", "churn prediction", "likely to convert", "who will do X", "predicted_p_",
  "autoresearch_prediction", "realized AUC", "champion model".

Working with autoresearch

Autoresearch answers one standing question per model: **who in a population will do a target within a horizon?** For example, "which active users will open a report in the next 7 days?".

1. The user names a **target** (an event or a PostHog action), a **population** and a **horizon** in days. 2. A training agent runs in a PostHog sandbox. It writes feature SQL and a model, scores each experiment on a holdout set, keeps what improves holdout AUC and discards the rest. 3. The server picks the **champion** from the kept experiments. The agent proposes; the backend decides. 4. Every cadence (daily by default, at 02:00 UTC), the champion scores the inference population. Each scored person gets an `autoresearch_prediction` event with their probability. When the model's `write_person_property` is on, a person who resolves to a current distinct ID also gets the model's output person property, for example `predicted_p_adopt_insights_14d`. It is off by default for new models. Turn it on with `autoresearch-partial-update` before you target people by score in a flag, cohort, workflow or insight. Turning it off removes the property from the people the model scored. Changing the setting needs the `person:write` scope. 5. When a prediction date's horizon has passed, online validation checks the scores against what really happened and records **realized AUC**. 6. Training keeps going on a schedule. On each scoring day the model starts a research run (**explore**) until a run does not promote a better model, or until 5 research runs have run. After that it starts one research run every `research_interval_days` (**maintain**, default 7) after the latest training run, so a run started by hand resets the clock. With `research_interval_days` null the model trains only when someone asks. A champion that cannot score still gets a short rescue run. `training_phase` and `next_research_at` on `posthog:autoresearch-retrieve` say where the model is.

In the PostHog UI the entity is a **model**. The API and tools call it a **pipeline**. Use "model" when you talk to people.

Autoresearch is behind the `autoresearch` feature flag. Training runs in a cloud sandbox, so it also needs PostHog Desktop access. If the `autoresearch-*` tools are missing, the project probably does not have access yet.

Pick the job

| The user wants to | Start with | Reference | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Create a model | `posthog:autoresearch-resolve-template-create` or a custom definition, then `posthog:autoresearch-validate-create` | [defining-a-question.md](references/defining-a-question.md) | | Know if a model is any good | `posthog:autoresearch-retrieve`, then `posthog:autoresearch-online-performance-retrieve` | [reading-model-quality.md](references/reading-model-quality.md) | | Use the predictions | The output person property, or `posthog:execute-sql` on `autoresearch_prediction` | [using-predictions.md](references/using-predictions.md) | | Fix or steer a model | `posthog:autoresearch-training-runs-list`, `posthog:autoresearch-runs-list`, `posthog:autoresearch-suggestions-create` | [troubleshooting-and-steering.md](references/troubleshooting-and-steering.md) | | See what models exist | `posthog:autoresearch-list` | This page |

Create, train, score

The usual path is short. Each tool's description names its prerequisites and refusals, so read it with `info` before the first call.

1. **Resolve or define.** Templates cover the common questions (activity, inactivity risk, return after first use, feature adoption, repeat behavior). A custom definition works when none fits. See [defining-a-question.md](references/defining-a-question.md). 2. **Validate.** `posthog:autoresearch-validate-create` with the same target, horizon, lookback and populations you will create with. It returns the base rate, positive and negative counts and warnings. Fix anything that sets `can_proceed` to false, and tell the user about the non-blocking warnings. 3. **Create.** `posthog:autoresearch-create`. The new model is a `draft` until training starts. 4. **Train.** `posthog:autoresearch-train-create` starts an agent run that takes a while (often tens of minutes). It costs real sandbox and LLM time, so confirm with the user before you start one, and never start a second r