Creating runs
Writing instructions, titles and metadata, and what happens after you start a run.
- Can a run call external APIs or send data to other services?Runs can fetch web pages and use connected apps on your account. Don't paste credentials; connect services instead.FAQ
- Can Cosmos work on my GitHub repository?Cosmos works on its cloud computer. It can fetch public code, or use connected apps on your account; it can't reach your machine.FAQ
- Can I attach files or images to a run?Runs take text input only. Paste text into input, give a URL Cosmos can fetch, or keep files on your cloud computer.FAQ
- Can I change a run's title or metadata after creating it?No. title and metadata are set at creation. Keep anything that changes later in your own records, keyed by the run id.FAQ
- Can I limit how long a run takes or how many steps it uses?There's no request field for a time or step budget. Put limits in your instructions, watch the stream, and cancel if needed.FAQ
- Can I put passwords or API tokens in my instructions?No. Don't paste secrets into input. Connect services to your account instead, and treat runs as something others on your team may read.FAQ
- Can I send a follow-up message to a run that's already going?The Agent API has no endpoint for adding messages to a run. Start a new run that continues the work instead.FAQ
- Can I start lots of runs at the same time?Up to 5 runs can be queued or running per account. A sixth answers 429 too_many_runs. Queue the rest in your own code.FAQ
- Can I use the Agent API for things that aren't coding?Cosmos is built for coding work, but it can also browse, research and produce files. Here's what fits well.FAQ
- Can I write instructions in a language other than English?input is plain text, so you can write in other languages. Say which language you want the answer and code comments in.FAQ
- Can the Agent API notify my server when a run finishes?The API doesn't describe webhooks. Keep an event stream open until the done event, or poll the run every few seconds.FAQ
- Does a run keep going if my script stops or my connection drops?Yes. Runs keep going if you disconnect, and long tasks continue past any single request's time limit, up to 150 steps.FAQ
- How can a new run continue work from an earlier run?Ask runs to keep work in a Cloud Repo, hosting or storage on your cloud computer, then point the next run at it by name.How-to
- How do I get structured JSON back from a run?Ask for it in the instructions and have Cosmos save it as an output file, then parse the file content from ?include=files.How-to
- How do I include code or logs in my instructions?Paste them into input inside fenced blocks, keep only the relevant parts, and stay within 20,000 characters.How-to
- How do I use metadata to link runs to my own records?Put your own ids in metadata (up to 2 KB of JSON). It's returned unchanged on the run, so you can match runs to tickets or users.How-to
- How do I write instructions that Cosmos does well?Write input like a ticket: the goal, the constraints and what "done" looks like. Name files, set limits and ask for proof.How-to
- How long does a run take?It depends on the task and tier. Small tasks finish quickly; big ones can take many steps, up to 150 per run.FAQ
- I'm new to this. What's a good first thing to ask Cosmos?Easy, fun first tasks for beginners and young coders, with example instructions you can copy.FAQ
- If my create request times out, will retrying start a duplicate run?A retry after a timeout may start a second run. Check GET /v1/runs for the first one before retrying, using metadata to find it.FAQ
- My instructions are longer than 20,000 characters. What can I do?input is capped at 20,000 characters. Trim it, link to the material, or keep large files on the cloud computer for Cosmos to read.Troubleshooting
- Should I let Cosmos deploy to my production servers?Treat agent changes like a pull request: review them and deploy through your own pipeline. Runs can host on clatterai.com for previews.FAQ
- What are good example instructions for common tasks?Copyable input examples for tests, bug fixes, scripts, docs, refactors and website checks, each with a clear "done" condition.Reference
- What are sub-agents in a run?For bigger jobs, Cosmos can split a run into parallel sub-agents, then bring the results together. Cancelling a run stops them too.Explainer
- What fields can I send when creating a run?POST /v1/runs takes input (required), title, tier and metadata. Here are the limits and defaults for each.Reference
- What happens if Cosmos needs to ask me something during a run?Runs can't receive replies mid-run. Cosmos decides and explains in its output, so state assumptions and preferences up front.FAQ
- What happens right after I create a run?The API answers 201 immediately with the run. Cosmos starts working on its cloud computer; follow it with the event stream or by polling.FAQ
- What is a run's title for, and can I leave it out?title is an optional short name (up to 80 characters). If you leave it out, the first line of input is used.FAQ
- Will the same instructions always give the same result?Not exactly. An agent makes choices as it works, so results can differ. Pin versions, specify steps and verify with tests.FAQ
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.