Runs · Docs | Vaelor

A run is one pass of the investigation agent over a case. The agent plans, searches public sources, reads pages and attached files, records evidence, and writes a cited report. Runs execute on background workers and survive restarts.

Start a run#

POSThttps://api.vaelor.chat/v1/osint/cases/{id}/runs

Body

requestIduuidRequired

Idempotency key. Resending the same ID with the same input returns the existing run. See Idempotency.

goalstringRequired

The goal for this run, 1–4,000 characters. Usually the case goal, refined after earlier runs.

materialstringDefault ""

Material for this run, up to 50,000 characters.

modelenumDefault medium

flash, medium or high. See Models.

curl https://api.vaelor.chat/v1/osint/cases/a41f9c6e-2b8d-4e17-9f3a-6c0d5e8b2a91/runs \
  -H "Authorization: Bearer $VAELOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "goal": "Map the public web footprint of the domain northwind-trading.example.",
    "material": "northwind-trading.example",
    "model": "medium"
  }'

const run = await fetch(`https://api.vaelor.chat/v1/osint/cases/${caseId}/runs`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VAELOR_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ requestId: crypto.randomUUID(), goal, material, model: 'medium' })
}).then((response) => response.json())

run = requests.post(
    f"https://api.vaelor.chat/v1/osint/cases/{case_id}/runs",
    headers={"Authorization": f"Bearer {os.environ['VAELOR_API_KEY']}"},
    json={"requestId": str(uuid.uuid4()), "goal": goal, "material": material, "model": "medium"},
).json()

Response202

JSON

{ "id": "r_7c1e4b02", "status": "queued" }

Run lifecycle#

Status	Meaning
`queued`	Waiting for a worker.
`running`	The agent is collecting evidence.
`reporting`	Writing the final report.
`completed`	Finished with a full report.
`partial`	Stopped early — for example out of credits — with a report of what was found.
`cancelled`	Stopped by you.
`failed`	Ended with an error; see the run's `error`.

Billing#

1 credit is reserved when the run starts. Each model step is then charged at the tier's token rates, and each web search and page read as a tool call. If your balance runs out mid-run, the run ends as partial and still writes a report.

Stop a run#

DELhttps://api.vaelor.chat/v1/osint/cases/{id}/runs

Asks the active run on the case to stop. The run finishes its current step, then moves to cancelled.

Shell

curl -X DELETE https://api.vaelor.chat/v1/osint/cases/a41f9c6e-2b8d-4e17-9f3a-6c0d5e8b2a91/runs \
  -H "Authorization: Bearer $VAELOR_API_KEY"

Response200

JSON

{ "stopping": true }

Errors#

Status	When
`402`	Not enough credits to start the run.
`404`	The case doesn't exist.
`409`	You already have an active run, or the `requestId` was reused with different input.
`503`	Investigations are temporarily unavailable.