API reference

Runs

Start an AI workflow and follow it. Runs are asynchronous: starting one answers at once with a queued run, and the run begins within about a minute. Read it back with Get a run until its status is final.

Start a run

Queues a run of the workflow and answers at once with 202 and the queued run. The run begins within about a minute and runs for up to two minutes; follow it with Get a run. It runs with everything in the account the key can reach, and its AI use is billed to the account like any other run, under Tellagent. A key with a monthly spend cap stops a run that reaches it.

Idempotency-Key is required. Send a new unique value (a UUID is ideal) for each run you mean to start, and the same value again if you retry: a retry with the same key and the same request returns the first answer, with Idempotent-Replay: true, and never starts a second run. If the first request did not finish, the retry answers 409 idempotency_outcome_unknown and nothing is run again; list the workflow's runs to see whether it started. Keys are remembered for 24 hours.

Runs take no inputs in v1, so the body is {} or empty. A run that stops at a Human checkpoint waits for someone to approve it in the hub.

Parameters

Response 202

Errors

• 400 The request is not valid.
• 401 No valid API key.
• 402 Not enough credit to start a run.
• 403 The key may not do this.
• 404 Not found in this account.
• 409 The Idempotency-Key is busy, or its first request did not finish.
• 422 The body, the workflow or the Idempotency-Key cannot be used.
• 429 Too many requests, or too many runs.
• 500 Something went wrong on our side.

The codes are listed under Errors.

curl -X POST "https://api.veragen.ai/v1/workflows/{id}/runs" \
  -H "Authorization: Bearer $VERAGEN_API_KEY" \
  -H "Idempotency-Key: 6f1d2c3b-run-2026-10-03-1420" \
  -H "Content-Type: application/json" \
  -d '{}'

const res = await fetch("https://api.veragen.ai/v1/workflows/{id}/runs", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.VERAGEN_API_KEY}`, "Idempotency-Key": "6f1d2c3b-run-2026-10-03-1420", "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
const data = await res.json();

import os, requests

res = requests.post(
    "https://api.veragen.ai/v1/workflows/{id}/runs",
    headers={"Authorization": f"Bearer {os.environ['VERAGEN_API_KEY']}", "Idempotency-Key": "6f1d2c3b-run-2026-10-03-1420"},
    json={},
)
data = res.json()

{
  "id": "4b7e1c2d-3f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "workflow_id": "3f6c1d2e-8a4b-4f7e-9c21-5d0e7a1b2c3d",
  "status": "queued",
  "trigger": "api",
  "created_at": "2026-10-03T14:20:00.000Z"
}

List a workflow's runs

The workflow's runs, newest first, however they were started: from the hub, on a schedule, by chat or through the API.

Parameters

Response 200

Errors

• 400 The request is not valid.
• 401 No valid API key.
• 403 The key may not do this.
• 404 Not found in this account.
• 429 Too many requests.
• 500 Something went wrong on our side.

The codes are listed under Errors.

curl "https://api.veragen.ai/v1/workflows/{id}/runs?limit=25" \
  -H "Authorization: Bearer $VERAGEN_API_KEY"

const res = await fetch("https://api.veragen.ai/v1/workflows/{id}/runs?limit=25", {
  headers: { Authorization: `Bearer ${process.env.VERAGEN_API_KEY}` },
});
const data = await res.json();

import os, requests

res = requests.get(
    "https://api.veragen.ai/v1/workflows/{id}/runs",
    params={"limit": 25},
    headers={"Authorization": f"Bearer {os.environ['VERAGEN_API_KEY']}"},
)
data = res.json()

{
  "data": [
    {
      "id": "4b7e1c2d-3f5a-4b6c-8d7e-9f0a1b2c3d4e",
      "workflow_id": "3f6c1d2e-8a4b-4f7e-9c21-5d0e7a1b2c3d",
      "status": "succeeded",
      "trigger": "api",
      "summary": "Completed 3 steps (3 ran).",
      "created_at": "2026-10-03T14:20:00.000Z",
      "started_at": "2026-10-03T14:20:00.000Z",
      "finished_at": "2026-10-03T14:21:04.512Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Get a run

A run, its blocks and what it was billed. Poll it (every few seconds is plenty) until status is final: succeeded, failed, partial (stopped at a time, step or spend limit), rejected or cancelled. awaiting_approval means it stopped at a Human checkpoint and waits for someone in the hub.

Parameters

Response 200

Errors

• 400 The request is not valid.
• 401 No valid API key.
• 403 The key may not do this.
• 404 Not found in this account.
• 429 Too many requests.
• 500 Something went wrong on our side.

The codes are listed under Errors.

curl "https://api.veragen.ai/v1/runs/{id}" \
  -H "Authorization: Bearer $VERAGEN_API_KEY"

const res = await fetch("https://api.veragen.ai/v1/runs/{id}", {
  headers: { Authorization: `Bearer ${process.env.VERAGEN_API_KEY}` },
});
const data = await res.json();

import os, requests

res = requests.get(
    "https://api.veragen.ai/v1/runs/{id}",
    headers={"Authorization": f"Bearer {os.environ['VERAGEN_API_KEY']}"},
)
data = res.json()

{
  "id": "4b7e1c2d-3f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "workflow_id": "3f6c1d2e-8a4b-4f7e-9c21-5d0e7a1b2c3d",
  "status": "succeeded",
  "trigger": "api",
  "summary": "Completed 3 steps (3 ran).",
  "created_at": "2026-10-03T14:20:00.000Z",
  "started_at": "2026-10-03T14:20:00.000Z",
  "finished_at": "2026-10-03T14:21:04.512Z",
  "billed_micros": 41250,
  "steps": [
    {
      "node_id": "n1",
      "node_kind": "source.web",
      "status": "succeeded",
      "ms": 8120,
      "error": null
    },
    {
      "node_id": "n2",
      "node_kind": "agent",
      "status": "succeeded",
      "ms": 15433,
      "error": null
    },
    {
      "node_id": "n3",
      "node_kind": "output.project",
      "status": "succeeded",
      "ms": 210,
      "error": null
    }
  ]
}