# Quick runs and endpoints: stateless and stateful

There are two honest ways to use a model on your data. Ask a one-off question, or build something you will keep asking.

## The quick run

One pass, one full bundle, nothing kept. It suits agents, pipelines, and one-shot analysis. Data is used transiently and nothing is registered.

cURLPython`curl -X POST 'https://api.example.com/v2/run' \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tables": [{"name": "orders", "rows": [{"id": 1, "amount": 42.5}]}]}'
``import os, requests

r = requests.post(
    "https://api.example.com/v2/run",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"tables": [{"name": "orders", "rows": [{"id": 1, "amount": 42.5}]}]},
)
print(r.json()["sector"])
`

## The endpoint

A persistent object that bundles a base model, pinned data snapshots, configuration, and a held-out report, exposed at a stable URL. The ID and URL never change, even when the name does.

## Three independent versions

An endpoint's state has three parts that change on their own schedules: the base model generation, the data snapshot, and the configuration revision. Every change is additive, and the endpoint keeps serving while it happens.

## Lifecycle

- **Create.** Returns a job straight away. The endpoint goes live within minutes. Check the held-out report before sharing results.
- **Serve.** Score request rows against the pinned state.
- **Refresh.** Re-sync the data into a new snapshot and re-score on a fresh split.
- **Upgrade.** Re-run the same pinned data on a newer base and report the score change.

## Two rules that keep it safe

- **Every mutating operation mints a report.** Create, refresh, and upgrade each leave a record of what changed and how the score moved.
- **One mutating job at a time per endpoint.** A second request gets a clear conflict, not a race.