---
title: "Whether one generator followed another beyond chance: the labelled report."
method: POST
path: "/api/agents/run/pull_analyse"
tags: ["Lab"]
---

# Whether one generator followed another beyond chance: the labelled report.

`POST /api/agents/run/pull_analyse`

## Request

- Base URL: `https://tomorrowlives.com`
- URL: `https://tomorrowlives.com/api/agents/run/pull_analyse`
- Auth: HTTP bearer

Analyses the sessions of one condition (one session, a list, or {"sessions": [...]}) together, and each alone, and returns the report: its label (significant; null, with the smallest effect these sessions could have found; unlabelled, with what is missing; or not testable) and the sentence behind it, the mean signed shift against three surrogate families, the placebos, the four cells (deliberate, programmed, luck and sync), intended against unintended changes, recovery, locking, and the report's hash. prereg registers the run; replication analyses a second set under it, beside the first; measure is phase (timing, the default) or state (the stance along the leader's declared direction, for two agents); surrogates (19 to 9,999, default 199) sets an unregistered run's draws a family, a registered run taking its pre-registration's; seed fixes them; a session of three or more generators is tested pair by pair, every ordered pair with its own ledger and the correction for their number, unless pairs is false; detail adds every pull record. It costs one unit for each 40,000 session-draws over a thousand events (a session's own reading counts as 200 draws), at least 1. A group costs its ordered pairs' worth. A call priced at more than 2 units is queued: the answer is 202 with a job id and its price, GET /api/agents/jobs/<job> (or the MCP tool job) says when it is done, and the whole report comes back as report.json beside a short verdict. A queued call is refused on the free plan with 402: its units buy only calls that answer at once, and queued jobs need a paid plan (a pass or the card plan). Sessions are not kept.

## Request body

- object
  - `sessions` union, required: One session, a list of sessions, or {"sessions": [...]} of one condition, as JSON documents.
    - object
    - 0[] (unresolved $ref)
  - `prereg` 0 (unresolved $ref)
  - `replication` union: Sessions of a replication, analysed against the first set.
    - 0 (unresolved $ref)
    - 1 (unresolved $ref)
  - `surrogates` integer: How many surrogate runs to draw for the null, 19 to 9999.
  - `seed` integer: A whole number that makes the run reproducible: the same seed and inputs give the same answer.
  - `measure` string: The measure to analyse, by name.
  - `pairs` boolean: True to analyse performer pairs as well.
  - `detail` boolean: True to return the fuller per-session detail.

## Response `200`

The job's result and files

- Job
  - `job` string
  - `verb` string
  - `units` integer
  - `ms` integer
  - `result` unknown
  - `files` object[]
    - `name` string
    - `bytes` integer
    - `content_type` string
    - `url` string
    - `url_expires_at` string, date-time

## Other responses

- `202`: Queued: the job id, its price and where to poll. Poll GET /api/agents/jobs/{job} until it is ok, refused or failed.
- `400`: The input is not valid
- `401`: No valid API key
- `402`: A pass or a payment is needed: a queued render on the free plan, a unit pack on the free plan (pass_required), a card plan's past-due renewal, or, on the free plan, an owner who has not confirmed their email yet (owner_unconfirmed; a pass needs no confirmation); or a payment did not go through (payment_failed, payment_token_unusable), and nothing was charged
- `403`: The account is suspended, the paying card is not from the United States (region_not_supported), or the address named as its owner said it is not theirs and costed runs are paused until a new owner is named (owner_removed)
- `413`: The input or the output is over its cap; a job stopped by the output cap is not charged
- `422`: The engine refused the input, a limit of the service's refused it (error: video_limit or pull_limit) or stopped the job, or the content policy refused the input (error: content_policy)
- `429`: A limit was hit; reset_at says when it lifts (also in Retry-After)
- `503`: The engines are busy or not installed
- `504`: The job ran past its time and was stopped

---

[API](https://skmtc.dev/tomorrowlives/apis/tomorrow-lives-engines.md) · [All operations](https://skmtc.dev/tomorrowlives/apis/tomorrow-lives-engines/llms.txt) · [OpenAPI document](https://skmtc.dev/tomorrowlives/apis/tomorrow-lives-engines/revisions/afc3d67322ac?raw)