Skip to main content

​
Retrieve task artifacts

Do this when an agent produced a file you need — a report, a chart, a transformed dataset. Do not use this to browse workspace or project storage; these endpoints serve one task’s workspace and nothing else. Artifacts survive the sandbox that produced them. They are committed to durable storage before the tool call that created them returns, so a file listed here is a file that exists.

​
Prerequisites

  • A task id and its agent id.
  • An API key for the workspace that owns the task. A task in another workspace returns 404, not 403.

​
Steps

​
1. List what the task produced

path is always tasks/{task_id}/workspace/{relative_path}. download_url is an AgentArea API path, not an object-store URL — it is relative, so prefix it with your API base. Inputs you attached and outputs the agent wrote both appear here. Tell them apart by prefix: attachments land under inputs/attachments/.

​
2. Download one file

The response streams with Content-Length and a Content-Disposition filename. The body is verified against the stored SHA-256 before the first byte is sent, so a partial or corrupted object fails the request instead of writing a bad file. Or follow the download_url from the listing directly:

​
3. Download everything

There is no archive endpoint. Loop the listing:

​
Verify

Confirm the downloaded bytes match what the task committed. The listing’s size is the manifest’s recorded size:
Equal sizes plus a 200 response means the digest check passed on the server — the endpoint does not return a body it could not verify.

​
Troubleshooting

The listing is empty on a completed task. The agent answered from context without writing files. Only files committed to the task workspace appear here; text in the final response is not an artifact. Read final_response from GET /v1/agents/{agent_id}/tasks/{task_id}/summary instead. 404 on a path that appears in the listing. The artifact_path segment must be the full tasks/{task_id}/workspace/... value, repeated after /artifacts/files/. Passing only the relative tail (out/summary.md) 404s, because the endpoint validates that the first two segments match the task. Copy download_url rather than assembling the path. 404 on anything outside workspace/. Only the tasks/{task_id}/workspace/ subtree is downloadable through this endpoint. Other prefixes under the task return 404 by design. The agent said it wrote a file but nothing is listed. Copy-out happens when the shell tool returns, and it refuses files over 16 MiB per artifact or beyond the 1 GiB per-task durable budget. A refused copy is reported as an error on that tool result, so check the tool.result events for the call that created it — see Debug a failed task. A large download is slow to start. Verification reads and hashes the whole object before yielding the first byte, spooling to disk past 8 MiB. Time to first byte scales with file size; this is the integrity guarantee, not a stall. The expires_in query parameter appears to do nothing. It does nothing. It is accepted for backwards compatibility; these links are API routes behind normal authorization and do not expire.