---
title: "What a twin, an analysis or a lab theory would cost, before it is called: units, whether it is queued, the limit it breaks."
method: POST
path: "/api/agents/run/pull_cost"
tags: ["Lab"]
---

# What a twin, an analysis or a lab theory would cost, before it is called: units, whether it is queued, the limit it breaks.

`POST /api/agents/run/pull_cost`

## Request

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

Prices a call without making it: give the arguments of pull_twin (a twin document, or condition, coupling, planted, field, sessions as a number and seed; nothing at all is the default twin), of pull_analyse (a sessions document, with prereg, replication, surrogates and pairs) or of pull_lab (a theory, one-dimensional or with a model, or reference skyrme or hopfion). The engine counts the document without running it: a twin's or an analysis's sessions, events, draws, work and an estimate of CPU-seconds (cpu_pairs and cpu_note say which part of a group's estimate repeats for each pair), a lab theory's lattice, the steps priced and its CPU-seconds. The answer adds what this service makes of the count: for, the call it priced; units, what that call would be charged, null when it would be refused (a queued call's price is the engine's count, so a lattice or a system generator, which the formula that routes a call cannot see, is priced as it will be); queued, whether it would be queued (202) rather than answer at once; within_limits, and when it is false the limit it breaks. A one-dimensional theory is counted too and is queued like any theory (an ordinary one at 1 unit), and the one-dimensional references, which are not counted, are refused here by name. Runs and renders nothing. Costs no units.

## Request body

- object
  - `twin` object: A twin document written inline, as for pull_twin.
  - `condition` string: The condition to price: P or R followed by 1 to 4.
  - `coupling` number: Coupling to price at, 0 to 1.
  - `planted` number[]: The planted effect as a pair of numbers between -2 and 2.
  - `field` string: The field to price in, by name.
  - `seed` integer: A whole number that makes the run reproducible: the same seed and inputs give the same answer.
  - `sessions` union: A session count for a twin run, or the sessions of an analysis to price.
    - integer
    - Twin (unresolved $ref)
    - Twin[] (unresolved $ref)
  - `prereg` Twin (unresolved $ref)
  - `replication` 1 (unresolved $ref)
  - `surrogates` integer: Surrogate runs to price, 19 to 9999.
  - `pairs` boolean: True to price the pair analysis as well.
  - `theory` Twin (unresolved $ref)
  - `reference` union: True, or a reference name, to price the lab's reference run.
    - true
    - string

## 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

- `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)