Running and runs

POST /v1/task-runs runs a task. By default it waits and answers with the finished run. With background: true it queues the run and answers 202 at once; POST /v1/task-runs/batch queues up to 1000 runs of one task in one request. Every run is a record you can read, list, cancel and delete. Both need the editor role. This page is about standalone runs. A task entered by an agent mid-conversation creates no run record and is recorded in that call’s transcript instead; see agent tasks.

A run executes for real: tools call your endpoints with your secrets, MCP servers spend your credits, and the model spends tokens on your provider key. The dashboard’s Run panel does the same.

curl -sS -X POST https://api.talqing.com/v1/task-runs \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 330 \
  -d '{
    "task_id": "0b7d4c92-3e51-4a86-9f2d-71c0a4e58b13",
    "vars": { "email": "priya@northwind.example" }
  }'

const run = await talqing.taskRuns.create({
  createTaskRunRequest: {
    task_id: "0b7d4c92-3e51-4a86-9f2d-71c0a4e58b13",
    vars: { email: "priya@northwind.example" },
  },
});

if (run.status === "failed") {
  console.error(run.error?.type, run.error?.message);
} else {
  console.log(run.output);
}

run = talqing.task_runs.create(
    task_id="0b7d4c92-3e51-4a86-9f2d-71c0a4e58b13",
    vars={"email": "priya@northwind.example"},
)

if run["status"] == "failed":
    print(run["error"]["type"], run["error"]["message"])
else:
    print(run["output"])

An inline request lasts up to the task’s timeout_seconds (default 300, max 600). Set your HTTP client’s read timeout above it, or use background: true. A client that gives up loses the response, not the spend.

What runs

Field	Type	Meaning
`task_id`	uuid	A task in this workspace. Exclusive with `task`.
`task_version`	integer \| `"draft"` \| omitted	Omitted: the published version (`400` `publish '<name>' before running it` if none). A number: that frozen version (`404` if missing). `"draft"`: the unpublished config, held to publish validation; a draft that could not publish is refused with those errors.
`task`	object	A whole task config, run and stored nowhere else. No versions.
`task_override`	object	Changes for this run only, in the same shape as the config: objects merge, lists replace, `null` clears. `{"llm": {"model": "…"}}` tries another model.

The resolved config — base, override and pinned tool versions — is stored on the run as config, so you can always see exactly what ran. A config that does not hold together after the override is a 422 listing each problem.

Inputs, labels and idempotency

Field	Type	Meaning
`vars`	object of strings	Values for the task’s text inputs. See inputs and output.
`files`	object	One PDF per `file` input: `{"url": "https://…"}` or `{"data_url": "data:application/pdf;base64,…"}`, with an optional `filename`.
`metadata`	object of strings	Up to 16 labels of your own (`key` up to 40 of `A-Za-z0-9_.-`, value up to 500 characters). Filterable, and kept when the run’s content is deleted.
`idempotency_key`	string	Up to 255 characters. Resending the same key returns the existing run instead of starting another, with the header `Idempotent-Replayed: true` — even after the task is republished or deleted. The key is held to the request as you sent it; the same key with different inputs, labels, task selection or `background` is a `409`. A resend returns the run as it stands — still `running` if it has not finished.
`background`	boolean	`true` queues the run and answers `202` with `status: "queued"`.

A request body over 50 MB is a 413. Inputs that do not match the task — an undeclared name, a missing required input, a file sent under vars — are a 400 before anything is stored.

Background runs and batches

curl -sS -X POST https://api.talqing.com/v1/task-runs/batch \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "0b7d4c92-3e51-4a86-9f2d-71c0a4e58b13",
    "runs": [
      { "files": { "cv": { "url": "https://files.example.com/c_41.pdf" } },
        "metadata": { "candidate_id": "c_41" }, "idempotency_key": "c_41-v1" },
      { "files": { "cv": { "url": "https://files.example.com/c_42.pdf" } },
        "metadata": { "candidate_id": "c_42" }, "idempotency_key": "c_42-v1" }
    ]
  }'

{ "runs": [
  { "id": "5a2e9d10-…", "status": "queued", "idempotency_key": "c_41-v1", "deduplicated": false },
  { "id": "8c1f7e44-…", "status": "queued", "idempotency_key": "c_42-v1", "deduplicated": false }
] }

A batch names the task once (task_id, task_version, task, task_override) and takes 1–1000 runs, each with its own vars, files, metadata and idempotency_key. Results come back in input order.
All or nothing. One invalid item refuses the whole batch with a 400 naming it (runs[3]: 'cv' is required and has no default); nothing is queued.
Your workspace runs up to 3 background runs at a time and queues the rest, oldest first, across every batch and single background run. A submission is never refused for load, only when 100,000 runs are already queued (429).
Files are not fetched at submission. A URL is downloaded when the run starts.

Find out when runs finish by subscribing a webhook to task_run.completed, sent once per run as it reaches completed, failed or canceled, or by polling GET /v1/task-runs.

Retries

A background run is tried again, up to 3 tries in all, when:

the worker running it stopped — a deploy or a crash — whatever it had done; or
the model provider failed with an error it marks as transient, or the platform failed, before any tool ran. A worker stop retries from the start even after tools acted, so make side-effecting tools safe to repeat.

Retries back off 30 then 60 seconds. Everything else fails on the first try. tries on the run says how many there were, and usage and provider_cost add up across them. Inline runs are never retried.

Response

{
  "id": "5a2e9d10-64bc-4f37-8e91-2c7b0d4a6f58",
  "task_id": "0b7d4c92-3e51-4a86-9f2d-71c0a4e58b13",
  "task_name": "Score a CV",
  "task_version": 3,
  "status": "completed",
  "error": null,
  "output": { "score": 72, "criteria": [{ "name": "Kubernetes", "verdict": "meets", "quote": "ran Kubernetes in production" }] },
  "metadata": { "candidate_id": "c_41" },
  "idempotency_key": "c_41-v1",
  "background": true,
  "tries": 1,
  "created_at": "2026-08-30T09:13:58.020Z",
  "started_at": "2026-08-30T09:14:02.118Z",
  "ended_at": "2026-08-30T09:14:19.402Z",
  "duration_ms": 17284,
  "provider_cost": 0.0184,
  "billing_status": "computed",
  "content_deleted_at": null,
  "content_expires_at": null,
  "config": { "name": "Score a CV", "…": "…" },
  "vars": {},
  "files": [{ "input": "cv", "filename": "c_41.pdf", "bytes": 81244, "pages": 2, "text": "[page 1]\nPriya Raman…", "images": [] }],
  "trace": [],
  "steps_used": 1,
  "max_steps": 25,
  "attempts": 1,
  "usage": [{ "provider": "openai", "model": "gpt-5.4-mini", "input_tokens": 3120, "input_cached_tokens": 0, "output_tokens": 410, "purpose": "conversation", "priority": false }],
  "cancel_requested_at": null
}

Field	Type	Meaning
`task_id`	uuid \| null	Null for an inline `task`, and once the task is deleted; runs survive deletion.
`task_name`	string \| null	The task’s name at run time.
`task_version`	integer \| null	The published version that was the base; null for `"draft"` and inline runs.
`status`	`queued` \| `running` \| `completed` \| `failed` \| `canceled`
`error`	`{type, message}` \| null	See errors and limits.
`output`	object \| null	The validated `submit_result` arguments; null unless `completed`.
`tries`	integer	How many times a worker started the run.
`created_at` / `started_at`	timestamp	Submitted, and started by a worker. A queued run has no `started_at`.
`config`	object \| null	The exact config that ran. Null on runs from before it was stored, and after deletion.
`files`	array	Each PDF as the model saw it: `text` is the extracted text; `images` are pages with no selectable text, with signed `url`s valid for an hour.
`trace`	array	Every model message and tool call, in order.
`steps_used`	integer	Rounds used by the busiest attempt.
`attempts`	integer	1–3: how many times the model was prompted to produce the result, within the last try.
`usage`	array	Tokens per provider and model, summed across tries.
`provider_cost`	number \| null	Estimated spend on your provider key, in USD.
`billing_status`	`pending` \| `computed` \| `unpriceable` \| `skipped`	`skipped`: nothing reached a provider. `unpriceable`: the model is missing from the catalog, so cost is not reported as zero.
`content_deleted_at`	timestamp \| null	When the run’s content was deleted.
`content_expires_at`	timestamp \| null	When your retention policy will delete it.

A failed run is still a 200 with status: "failed"; its trace, usage and cost are on the response.

`steps_used` and `attempts`

A step is one model → tools → model round, not one tool call. Four tools called in one reply are one step. A successful run’s last step is the submit_result call, so a task with no other tools reports steps_used: 1.
A run that ends without calling submit_result is re-prompted, up to twice, and each re-prompt gets a fresh step budget. steps_used reports the busiest attempt, the number max_steps governs.
So attempts: 3 with max_steps: 25 can mean up to 75 rounds; timeout_seconds is the real bound.

The trace

[
  { "step": 1, "kind": "message", "name": "assistant", "result": "I'll look up the domain first.", "args": null, "ms": null, "truncated": false },
  { "step": 2, "kind": "tool", "name": "web_lookup", "args": { "domain": "northwind.example" }, "result": { "title": "Northwind Tools", "employees": 240 }, "ms": 812, "truncated": false }
]

kind: "tool": name is the tool as the model called it (namespaced for MCP tools); args and result are parsed JSON when possible, else text; ms is the call’s duration.
kind: "message": text the model wrote, in result; name is assistant and ms is null.
Workspace secret values are masked before storage.
Fields over 4,000 characters are cut and the entry’s truncated is true. At most 200 entries are kept.
Provider tools such as web_search run inside the provider and do not appear.

Listing runs

GET /v1/task-runs lists runs newest first, without config, inputs or trace. Filter with task_id, status, created_after, created_before and metadata, repeated as key:value pairs that must all match (limit default 50, max 200; see pagination). GET /v1/task-runs/{run_id} returns one run in full. GET /v1/tasks carries each task’s last_run in the same list shape.

curl -sS -G https://api.talqing.com/v1/task-runs \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  --data-urlencode "metadata=candidate_id:c_41" \
  --data-urlencode "status=completed"

Task runs do not appear in the Observability charts. Their spend shows only in run history and on an email batch page, where each drafted row links to its run.

Canceling

POST /v1/task-runs/{run_id}/cancel cancels a queued run at once and returns it canceled. A running background run is returned still running with cancel_requested_at set, and stops within a few seconds as canceled with the message canceled while running. An inline run cannot be canceled (409); it ends at its timeout. Canceling a finished run is a 409.

Deleting

DELETE /v1/task-runs/{run_id} answers 202 and deletes the run’s vars, files (with their stored page images), output, trace and config, and the message on its error, usually within seconds. The run itself stays with its status, error type, metadata, idempotency_key, timings, usage and cost, and content_deleted_at is set. A queued run is canceled first; a running one is asked to stop and deleted once it has. POST /v1/task-runs/delete with {"metadata": {"candidate_id": "c_41"}} (and optionally task_id) does the same for every matching run and answers 202 {"count": n}. metadata must name at least one pair. A workspace retention policy deletes task-run content the same way, the set number of days after each run ends.

Errors and limits

Every error.type and its fix.

Inputs and output

Text, untrusted and PDF inputs; nested output.

Get started

Build

Guides

Running and runs

What runs

Inputs, labels and idempotency

Background runs and batches

Retries

Response

`steps_used` and `attempts`

The trace

Listing runs

Canceling

Deleting

Next

Errors and limits

Inputs and output

​What runs

​Inputs, labels and idempotency

​Background runs and batches

​Retries

​Response

​steps_used and attempts

​The trace

​Listing runs

​Canceling

​Deleting

​Next

Errors and limits

Inputs and output

What runs

Inputs, labels and idempotency

Background runs and batches

Retries

Response

`steps_used` and `attempts`

The trace

Listing runs

Canceling

Deleting

Next