---
title: "Twin sessions run and analysed: the instrument proven, or its false-positive rate."
method: POST
path: "/api/agents/run/pull_twin"
tags: ["Lab"]
---

# Twin sessions run and analysed: the instrument proven, or its false-positive rate.

`POST /api/agents/run/pull_twin`

## Request

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

Runs twin sessions (scripted performers and the machine follower, each session drawn, sealed, released, closed and opened like a real one) and analyses them under the twin's own pre-registration: how many sessions were labelled significant, that rate with its 95% interval, and the pooled report with its hash. Give a twin document (pull_schema lists its keys: others for a group, a room of beings, the system generator, a field lattice), or condition (P1 to P4, R1 to R4), coupling (0 to 1) and planted ([intended, unintended] gains, each -2 to 2) for the engine's default pair; field (toda) strings a lattice between leader and follower. Uncoupled twins measure the false-positive rate; coupled ones should come out significant. The same document and seed give the same report hash as ae_pull itself. sessions is 1 to 1,000 (default 20, or the document's own); a schedule runs to at most 5,000 beats a session. 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 plain pair of up to 20 sessions and 2 units answers at once. Anything more, and any field, group, room or system generator, is queued and priced by the engine's own count of the twin (events a session at the schedule's widest gaps, its draws and its pairs, and the CPU-seconds a lattice or a spiking network takes), at least a unit for each 5 CPU-seconds it estimates, times the sessions. 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).

## Request body

- object
  - `twin` object: A twin document written inline; or use condition, coupling, planted and field instead.
  - `condition` string: The condition to run: P or R followed by 1 to 4.
  - `coupling` number: How strongly the follower is coupled to the performer, 0 to 1.
  - `planted` number[]: The planted effect as a pair of numbers between -2 and 2.
  - `field` string: The field to run the twins in, by name.
  - `sessions` integer: How many sessions to run, 1 to 1000.
  - `seed` integer: A whole number that makes the run reproducible: the same seed and inputs give the same answer.
  - `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)