List Artifacts

List artifacts produced by a workflow run.

Paginated by the producing step’s step_id (sorted by started_at ascending). Pass after for the next page, before for the previous page — mutually exclusive. step_id short-circuits pagination and returns the single attached artifact.

Filters: provide either run_id (list all artifacts in a run) or step_id (single-step lookup). When both are absent the request is rejected with 400.

GET /v1/workflows/artifacts

Python

from retab import Retab

client = Retab()

artifacts = client.workflows.artifacts.list(
    "run_abc123xyz",
    operation="conditional_evaluation",
)

for artifact in artifacts.data:
    print(artifact.operation, artifact.id)

200

{
  "data": [
    {
      "operation": "conditional_evaluation",
      "id": "ceval_abc123",
      "run_id": "run_abc123xyz",
      "step_id": "conditional-block-1",
      "selected_handles": ["wrong"],
      "matched_branch_id": "branch_wrong",
      "matched_condition_ids": ["condition_wrong_total"],
      "evaluations": [
        {
          "condition_id": "condition_wrong_total",
          "matched": true,
          "output_handle_id": "wrong",
          "left_value": 1200,
          "operator": "greater_than",
          "right_value": 1000
        }
      ],
      "created_at": "2026-03-12T09:00:04Z"
    },
    {
      "operation": "function_invocation",
      "id": "fninv_def456",
      "run_id": "run_abc123xyz",
      "step_id": "function-block-1",
      "inputs": {
        "total": 1200
      },
      "output": {
        "approved": false,
        "reason": "total exceeds review threshold"
      },
      "duration_ms": 248,
      "error": null,
      "created_at": "2026-03-12T09:00:05Z"
    }
  ],
  "list_metadata": {
    "before": null,
    "after": null
  }
}

List the dereferenced artifact records produced by one workflow run.

Returns the canonical { "data": [...], "list_metadata": { "before": null, "after": null } } pagination envelope shared with all Retab list endpoints. Each data item is a flattened workflow artifact record (operation-tagged dereferenced artifact); arbitrary operation-specific fields are preserved verbatim. Cursor pagination is not yet implemented for this endpoint — list_metadata is always { before: null, after: null }.

Use this when an integration needs to inspect all persisted records for a run, or when an MCP tool needs to answer questions such as why a conditional block selected a specific handle. The endpoint walks the run’s steps, follows each artifact ref, and returns the flattened records.

Filters:

• Provide either run_id or step_id. Use run_id to list every artifact produced by a run; use step_id to fetch the artifact attached to one step.
• operation limits results to one artifact operation, such as conditional_evaluation or function_invocation.
• block_id limits results to one producing block or step id.

Python

from retab import Retab

client = Retab()

artifacts = client.workflows.artifacts.list(
    "run_abc123xyz",
    operation="conditional_evaluation",
)

for artifact in artifacts.data:
    print(artifact.operation, artifact.id)

200

{
  "data": [
    {
      "operation": "conditional_evaluation",
      "id": "ceval_abc123",
      "run_id": "run_abc123xyz",
      "step_id": "conditional-block-1",
      "selected_handles": ["wrong"],
      "matched_branch_id": "branch_wrong",
      "matched_condition_ids": ["condition_wrong_total"],
      "evaluations": [
        {
          "condition_id": "condition_wrong_total",
          "matched": true,
          "output_handle_id": "wrong",
          "left_value": 1200,
          "operator": "greater_than",
          "right_value": 1000
        }
      ],
      "created_at": "2026-03-12T09:00:04Z"
    },
    {
      "operation": "function_invocation",
      "id": "fninv_def456",
      "run_id": "run_abc123xyz",
      "step_id": "function-block-1",
      "inputs": {
        "total": 1200
      },
      "output": {
        "approved": false,
        "reason": "total exceeds review threshold"
      },
      "duration_ms": 248,
      "error": null,
      "created_at": "2026-03-12T09:00:05Z"
    }
  ],
  "list_metadata": {
    "before": null,
    "after": null
  }
}

Authorizations

Api-Key · string · header · required

Query Parameters

run_id · string | null

Workflow run ID whose artifacts should be listed. Required unless step_id is provided.

operation · enum<string> | null

Optional artifact operation filter

Available options: extraction, split, classification, parse, edit, partition, conditional_evaluation, review_trigger_evaluation, while_loop_termination, api_call_invocation, function_invocation

block_id · string | null

Optional block_id or step_id filter

step_id · string | null

Optional step id filter. When provided, returns the single artifact attached to that step (or an empty list if the step has no artifact). run_id is not required when step_id is set — it is resolved from the step record.

before · string | null

Step id cursor: return the page before this step (mutually exclusive with after). Ignored when step_id is set.

after · string | null

Step id cursor: return the page after this step (mutually exclusive with before). Ignored when step_id is set.

limit · integer · default: 100

Maximum number of artifacts to return per page (1-200). Ignored when step_id is set (that path returns the single attached artifact).

Required range: 1 <= x <= 200

Response

200

application/json

Successful Response

A page of WorkflowArtifact resources. data holds the items and list_metadata carries the before/after cursors; pass after to fetch the next page.

data · WorkflowArtifact · object[] · required

Show child attributes

list_metadata · ListMetadata · object · required

Boundary resource IDs for page navigation.

Show child attributes