Results, listing and cancelling
Reading outputs and files, listing and fetching runs, and cancelling them.
- Can I delete a run and its data?The Agent API has no delete endpoint for runs. For permanent deletion of your data, email infrastructure@clatterlabs.xyz.FAQ
- GET /v1/runs/{id} answers 404 not_found. Why?There's no run with that id on your account. Check the id, the Account ID you're sending and whether the run came from the API.Troubleshooting
- How do I cancel a run?POST /v1/runs/{id}/cancel stops a queued or running run at its next step, along with any sub-agents it started.How-to
- How do I export my run history?Page through GET /v1/runs and save each run's fields; fetch ?include=files for outputs you need. Console Usage covers spend.How-to
- How do I find a run using my own ticket or user id?List runs and filter on metadata in your code. There's no server-side metadata search, so page through GET /v1/runs.How-to
- How do I get a run's final answer and files?Call GET /v1/runs/{id}. output holds the final answer; files lists saved outputs. Add ?include=files for their contents.How-to
- How do I list my runs and page through older ones?GET /v1/runs returns API runs newest first, 20 by default and up to 100. Pass the last created_at as before to get older ones.How-to
- How do I make sure I get a file back from a run?Ask Cosmos to save the file as an output, by name. It then appears in the run's files array, with content via ?include=files.How-to
- How do I stop all my runs at once?List runs with GET /v1/runs, then cancel each queued or running one with POST /v1/runs/{id}/cancel.How-to
- How long are my runs and their results kept?The Agent API docs don't publish a retention period for runs. Save outputs you need on your side, and ask us for deletion if needed.FAQ
- What do run ids and key ids look like?Run ids are UUIDs, like 4f0c2a6e-8d1b-4c3a-9f21-6b1e2d7c9a10. Key ids start with key_.Reference
- What does usage.tokens on a run tell me?usage.tokens is the number of tokens the run used. For cost, see the Console's Usage page or GET /v1/account.FAQ
- What happens if I cancel a run that already finished?Cancel stops queued or running runs. A run that's already completed, failed or cancelled has nothing left to stop.FAQ
- What is key_id on a run?key_id identifies the API key that created the run, so you can tell which integration started it.FAQ
- What time zone are run timestamps in?created_at and updated_at are ISO 8601 timestamps. The examples use UTC (ending in Z). Convert to local time in your app.FAQ
- Why does the run only show the first part of my input?The run object returns the first 4,000 characters of input. Cosmos still received your full instructions (up to 20,000 characters).FAQ
- Why is output null on my run?output is filled only when a run completes. While it's queued or running, or if it failed or was cancelled, output is null.Troubleshooting
Still need help?
Tried the steps above and still stuck? Email us. We usually reply within the first hour, and always within 24 hours. A full support team is with you.
Infrastructure questions, or permanent deletion of your data
infrastructure@clatterlabs.xyzFor deleting your whole account or the data of one service.