List immutable artifact versions published by a session with cursor pagination.
Endpoint
GET /agents/sessions/{session_id}/artifacts
Lists artifacts published by the specified session with cursor pagination. A successful call returns 200 and a list envelope.
Artifacts require the artifact capability to be enabled for the target workspace and are produced only after a turn completes successfully. After a hosted environment completes a turn, the list returns an empty array if artifact capability is not enabled for the workspace. When the current turn produces no new artifacts, the list can still contain artifacts from earlier turns; use the returned
turn_id to filter the current turn.A session with
environment.type=none has no associated environment, and the artifact list can return 404. Query artifacts after a hosted environment completes a turn.Query parametersenvironment_idstring (optional)Environment ID, optional, filter by environmentlimit integer (optional)Number of items per page, default 20, range 1–100order string (optional)Sort direction, asc or desc, default descafter string (optional)The last_id from the previous pagebefore string (optional)Reverse pagination cursor, optional; cannot be used with afterThe server does not currently filter by turn_id or path. Filter the paginated results on the client side. | Request example |
Response fieldsobjectstringList object type, fixed as listdata arrayArtifacts on the current page; can be emptyfirst_id string / nullID of the first item on the page; null for an empty pagelast_id string / nullID of the last item on the page; null for an empty pagehas_more booleanWhether the current direction has another pagedata item fields:The list response does not return underlying storage identifiers, signed download URLs, or credentials.
data item id stringArtifact version ID, not a file_idobject stringArtifact object type, fixed as agent.session.artifactsession_id stringOwning sessionenvironment_id stringSource environmentturn_id stringSource turnpath stringFull sandbox path when the artifact was generatedsize_bytes integerFile size in bytescreated_at integerCreation time, Unix seconds | Response example |
Error codes
| HTTP status | Error type / code | Solution |
|---|---|---|
400 | invalid_request_error / invalid_request_error | Fix limit and order as described in the query parameters, and avoid conflicting pagination parameters |
404 | not_found_error / not_found_error | Use a session ID that exists and is visible in the current workspace |
404 | not_found_error / not_found_error | Use the last_id returned by the previous page in the current collection as the cursor |
{"error":{"type","code","message","param"}}. Gateway errors can use a different structure. Keep the session ID, turn ID, environment ID, and x-request-id for troubleshooting.