> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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.

<RequestExample>
  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  import { Retab } from "@retab/node";

  const client = new Retab({ apiKey: process.env.RETAB_API_KEY });

  const artifacts = await client.workflows.artifacts.list({
    runId: "run_abc123xyz",
    operation: "conditional_evaluation",
  });

  for (const artifact of artifacts.data) {
    console.log(artifact.operation, artifact.id);
  }
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"
  	"log"

  	retab "github.com/retab-dev/retab/clients/go"
  )

  func ptr[T any](v T) *T { return &v }

  func main() {
  	ctx := context.Background()

  	client, err := retab.NewClient("")
  	if err != nil {
  		log.Fatal(err)
  	}

  	artifacts, err := client.Workflows.Artifacts.List(ctx, &retab.WorkflowArtifactsListParams{
  		RunID:     ptr("run_abc123xyz"),
  		Operation: ptr(retab.StepArtifactRefOperationConditionalEvaluation),
  	})
  	if err != nil {
  		log.Fatal(err)
  	}

  	for _, artifact := range artifacts.Data {
  		fmt.Println(artifact.Operation)
  		fmt.Println(artifact.ID)
  	}
  }
  ```

  ```ruby Ruby theme={null}
  require 'retab'

  client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])

  artifacts = client.workflows.artifacts.list(
    run_id: 'run_abc123xyz',
    operation: 'conditional_evaluation',
  )

  artifacts.data.each do |artifact|
    puts artifact.step_id
    puts artifact.matched_condition_ids
  end
  ```

  ```rust Rust theme={null}
  use retab::enums::WorkflowArtifactsOperation;
  use retab::resources::workflow_artifacts::ListParams;
  use retab::Retab;

  #[tokio::main]
  async fn main() -> Result<(), Box<dyn std::error::Error>> {
      let client = Retab::new(std::env::var("RETAB_API_KEY")?);

      let artifacts = client
          .workflows().artifacts()
          .list(ListParams {
              run_id: Some("run_abc123xyz".into()),
              operation: Some(WorkflowArtifactsOperation::ConditionalEvaluation),
              ..Default::default()
          })
          .await?;
      for artifact in &artifacts.data {
          println!("{} {:?}", artifact.id, artifact.operation);
      }
      Ok(())
  }
  ```

  ```php PHP theme={null}
  <?php
  require 'vendor/autoload.php';

  use Retab\Client;

  $client = new Client(apiKey: getenv('RETAB_API_KEY'));

  $result = $client->workflows()->artifacts()->list();
  print_r($result);
  ```

  ```csharp C# theme={null}
  using Retab;
  using RetabClient = Retab.Retab;

  var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
  var client = new RetabClient(apiKey);

  var result = await client.Workflows.Artifacts.ListAsync(new WorkflowArtifactsListOptions());
  Console.WriteLine(result);
  ```

  ```java Java theme={null}
  import com.retab.RetabClient;

  public final class Example {
    public static void main(String[] args) throws Exception {
      RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));

      var result = client.workflows().artifacts().list("run_abc123", null, "block_abc123", "step_abc123", null, null, 10L);
      System.out.println(result);
    }
  }
  ```

  ```curl cURL theme={null}
  curl -X 'GET' \
    'https://api.retab.com/v1/workflows/artifacts?run_id=run_abc123xyz&operation=conditional_evaluation' \
    -H 'Authorization: Bearer <your-api-key>'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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
    }
  }
  ```

  ```json 404 theme={null}
  {
    "detail": "workflow run not found"
  }
  ```
</ResponseExample>


## OpenAPI

````yaml GET /v1/workflows/artifacts
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://api.retab.com
security: []
paths:
  /v1/workflows/artifacts:
    get:
      tags:
        - Workflows
        - Workflow Artifacts
      summary: List Workflow Artifacts
      description: |-
        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.
      operationId: list_workflow_artifacts
      parameters:
        - in: query
          name: run_id
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Workflow run ID whose artifacts should be listed. Required unless
              `step_id` is provided.
            title: Run Id
          required: false
          description: >-
            Workflow run ID whose artifacts should be listed. Required unless
            `step_id` is provided.
        - in: query
          name: operation
          schema:
            anyOf:
              - enum:
                  - extraction
                  - split
                  - classification
                  - parse
                  - edit
                  - partition
                  - conditional_evaluation
                  - review_trigger_evaluation
                  - while_loop_termination
                  - api_call_invocation
                  - function_invocation
                type: string
              - type: 'null'
            description: Optional artifact operation filter
            title: Operation
          required: false
          description: Optional artifact operation filter
        - in: query
          name: block_id
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Optional block_id or step_id filter
            title: Block Id
          required: false
          description: Optional block_id or step_id filter
        - in: query
          name: step_id
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              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.
            title: Step Id
          required: false
          description: >-
            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.
        - in: query
          name: before
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Step id cursor: return the page before this step (mutually
              exclusive with `after`). Ignored when `step_id` is set.
            title: Before
          required: false
          description: >-
            Step id cursor: return the page before this step (mutually exclusive
            with `after`). Ignored when `step_id` is set.
        - in: query
          name: after
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Step id cursor: return the page after this step (mutually
              exclusive with `before`). Ignored when `step_id` is set.
            title: After
          required: false
          description: >-
            Step id cursor: return the page after this step (mutually exclusive
            with `before`). Ignored when `step_id` is set.
        - in: query
          name: limit
          schema:
            type: integer
            maximum: 200
            minimum: 1
            description: >-
              Maximum number of artifacts to return per page (1-200). Ignored
              when `step_id` is set (that path returns the single attached
              artifact).
            default: 100
            title: Limit
          required: false
          description: >-
            Maximum number of artifacts to return per page (1-200). Ignored when
            `step_id` is set (that path returns the single attached artifact).
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowArtifactList'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    WorkflowArtifactList:
      description: >-
        A page of `WorkflowArtifact` resources. `data` holds the items and
        `list_metadata` carries the `before`/`after` cursors; pass `after` to
        fetch the next page.
      properties:
        data:
          items:
            $ref: '#/components/schemas/WorkflowArtifact'
          type: array
          title: Data
        list_metadata:
          $ref: '#/components/schemas/ListMetadata'
      type: object
      required:
        - data
        - list_metadata
      title: WorkflowArtifactList
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
          default: []
      type: object
      title: HTTPValidationError
    WorkflowArtifact:
      properties:
        operation:
          type: string
          enum:
            - extraction
            - split
            - classification
            - parse
            - edit
            - partition
            - conditional_evaluation
            - review_trigger_evaluation
            - while_loop_termination
            - api_call_invocation
            - function_invocation
          title: Operation
          description: The operation that produced this artifact
        id:
          type: string
          title: Id
          description: Resource identifier
      additionalProperties: true
      type: object
      required:
        - id
        - operation
      title: WorkflowArtifact
      description: Dereferenced workflow artifact with operation-specific fields preserved.
    ListMetadata:
      properties:
        before:
          anyOf:
            - type: string
            - type: 'null'
          title: Before
        after:
          anyOf:
            - type: string
            - type: 'null'
          title: After
      type: object
      required:
        - after
        - before
      title: ListMetadata
      description: Boundary resource IDs for page navigation.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
          default: null
        ctx:
          type: object
          title: Context
          default: {}
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````