Skip to main content

List artifacts

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 parameters

environment_id string (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

curl -sS --get "$BASE_URL/agents/sessions/sess_xxx/artifacts" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1" \
  --data-urlencode "environment_id=ccarenv_xxx" \
  --data-urlencode "limit=100" \
  --data-urlencode "order=desc"

Response fields

object stringList 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.
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

{
  "object": "list",
  "data": [{
    "id": "artifact_xxx",
    "object": "agent.session.artifact",
    "session_id": "sess_xxx",
    "environment_id": "ccarenv_xxx",
    "turn_id": "turn_xxx",
    "path": "/workspace/outputs/report.txt",
    "size_bytes": 19,
    "created_at": 1793941200
  }],
  "first_id": "artifact_xxx",
  "last_id": "artifact_xxx",
  "has_more": false
}

Error codes

HTTP statusError type / codeSolution
400invalid_request_error / invalid_request_errorFix limit and order as described in the query parameters, and avoid conflicting pagination parameters
404not_found_error / not_found_errorUse a session ID that exists and is visible in the current workspace
404not_found_error / not_found_errorUse the last_id returned by the previous page in the current collection as the cursor
The error body has the shape {"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.