> ## 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 Workflow Blocks Executions

> List recent block executions for one workflow run block.

Cursor pagination matches the conventions used by
`GET /v1/extractions` — pass `after` from the previous page's
`list_metadata.after` to advance, `before` to step backwards, and
`order` to flip the sort direction. `run_id` + `block_id` are
required scope filters; without them this endpoint would expose
cross-run cursors that walk arbitrary block executions.

List workflow block executions for one run and block.

<RequestExample>
  ```python Python theme={null}
  from retab import Retab

  client = Retab()

  block_executions = client.workflows.blocks.executions.list(
      run_id="run_abc123xyz",
      block_id="blk_extract_1",
  )
  ```

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

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

  const block_executions = await client.workflows.blocks.executions.list({
    runId: "run_abc123xyz",
    blockId: "blk_extract_1",
  });
  ```

  ```go Go theme={null}
  block_executions, err := client.Workflows.Blocks.Executions.List(ctx, &retab.WorkflowBlockExecutionsListParams{
  	RunID:   ptr("run_abc123xyz"),
  	BlockID: ptr("blk_extract_1"),
  	Limit:   ptr(20),
  })
  ```

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

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

  block_executions = client.workflows.blocks.executions.list(
    run_id: 'run_abc123xyz',
    block_id: 'blk_extract_1',
  )
  ```

  ```rust Rust theme={null}
  use retab::resources::workflow_block_executions::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 block_executions = client
          .workflows()
          .blocks()
          .executions()
          .list(ListParams::new("run_abc123xyz", "blk_extract_1"))
          .await?;

      println!("{}", block_executions.data.len());
      Ok(())
  }
  ```

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

  use Retab\Client;

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

  $result = $client->workflows()->blocks()->executions()->list(
      runId: 'run_abc123',
      blockId: 'blk_extract_1',
  );
  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.Blocks.Executions.ListAsync(new WorkflowBlockExecutionsListOptions());
  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().blocks().executions().list("run_abc123", "block_abc123", null, null, 10L, null);
      System.out.println(result);
    }
  }
  ```

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

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [],
    "list_metadata": {
      "before": null,
      "after": null
    }
  }
  ```
</ResponseExample>


## OpenAPI

````yaml GET /v1/workflows/blocks/executions
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://api.retab.com
security: []
paths:
  /v1/workflows/blocks/executions:
    get:
      tags:
        - Workflows
        - Workflow Blocks Executions
      summary: List Block Executions
      description: |-
        List recent block executions for one workflow run block.

        Cursor pagination matches the conventions used by
        `GET /v1/extractions` — pass `after` from the previous page's
        `list_metadata.after` to advance, `before` to step backwards, and
        `order` to flip the sort direction. `run_id` + `block_id` are
        required scope filters; without them this endpoint would expose
        cross-run cursors that walk arbitrary block executions.
      operationId: list_block_executions
      parameters:
        - in: query
          name: run_id
          required: true
          schema:
            type: string
            title: Run Id
        - in: query
          name: block_id
          required: true
          schema:
            type: string
            title: Block Id
        - in: query
          name: before
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Before
          required: false
        - in: query
          name: after
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: After
          required: false
        - in: query
          name: limit
          schema:
            type: integer
            maximum: 100
            minimum: 1
            default: 20
            title: Limit
          required: false
        - in: query
          name: order
          schema:
            enum:
              - asc
              - desc
            type: string
            default: desc
            title: Order
          required: false
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockExecutionList'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    BlockExecutionList:
      description: >-
        A page of `BlockExecution` 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/BlockExecution'
          type: array
          title: Data
        list_metadata:
          $ref: '#/components/schemas/ListMetadata'
      type: object
      required:
        - data
        - list_metadata
      title: BlockExecutionList
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
          default: []
      type: object
      title: HTTPValidationError
    BlockExecution:
      properties:
        id:
          type: string
          title: Id
          description: Unique block execution ID
        workflow_id:
          type: string
          title: Workflow Id
          description: Workflow the block belongs to
        workflow_version_id:
          type: string
          title: Workflow Version Id
          description: Workflow version whose source run supplied inputs
        source_run_id:
          type: string
          title: Source Run Id
          description: Workflow run whose inputs were used
        block_id:
          type: string
          title: Block Id
          description: ID of the block that was executed
        block_type:
          type: string
          title: Block Type
          description: Type of the block
        lifecycle:
          oneOf:
            - $ref: '#/components/schemas/PendingBlockExecutionLifecycle'
            - $ref: '#/components/schemas/QueuedBlockExecutionLifecycle'
            - $ref: '#/components/schemas/RunningBlockExecutionLifecycle'
            - $ref: '#/components/schemas/CompletedBlockExecutionLifecycle'
            - $ref: '#/components/schemas/ErrorBlockExecutionLifecycle'
            - $ref: '#/components/schemas/CancelledBlockExecutionLifecycle'
            - $ref: '#/components/schemas/SkippedBlockExecutionLifecycle'
          title: Lifecycle
          description: Lifecycle state for this block execution.
          discriminator:
            propertyName: status
            mapping:
              cancelled:
                $ref: '#/components/schemas/CancelledBlockExecutionLifecycle'
              completed:
                $ref: '#/components/schemas/CompletedBlockExecutionLifecycle'
              error:
                $ref: '#/components/schemas/ErrorBlockExecutionLifecycle'
              pending:
                $ref: '#/components/schemas/PendingBlockExecutionLifecycle'
              queued:
                $ref: '#/components/schemas/QueuedBlockExecutionLifecycle'
              running:
                $ref: '#/components/schemas/RunningBlockExecutionLifecycle'
              skipped:
                $ref: '#/components/schemas/SkippedBlockExecutionLifecycle'
        handle_inputs:
          anyOf:
            - anyOf:
                - additionalProperties:
                    oneOf:
                      - $ref: '#/components/schemas/BlockExecJsonHandleInput'
                      - $ref: '#/components/schemas/BlockExecFileHandleInput'
                  type: object
                - type: 'null'
            - type: 'null'
          title: Handle Inputs
          description: >-
            Input payloads keyed by handle ID (file metadata for files, data for
            json)
        artifact:
          anyOf:
            - $ref: '#/components/schemas/StepArtifactRef'
            - type: 'null'
          description: Reference to the artifact produced by this block execution, if any.
        handle_outputs:
          anyOf:
            - anyOf:
                - additionalProperties:
                    oneOf:
                      - $ref: '#/components/schemas/BlockExecJsonHandleInput'
                      - $ref: '#/components/schemas/BlockExecFileHandleInput'
                  type: object
                - type: 'null'
            - type: 'null'
          title: Handle Outputs
          description: Output payloads keyed by handle ID
        routing_decisions:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Routing Decisions
          description: Active output handles for routing decisions
        duration_ms:
          anyOf:
            - type: number
            - type: 'null'
          title: Duration Ms
          description: Duration of the block execution in milliseconds
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the block execution record was created
        started_at:
          type: string
          format: date-time
          title: Started At
          description: When the block execution started
        completed_at:
          type: string
          format: date-time
          title: Completed At
          description: When the block execution completed
        handle_inputs_fingerprint:
          type: string
          title: Handle Inputs Fingerprint
        workflow_draft_fingerprint:
          type: string
          title: Workflow Draft Fingerprint
        block_execution_fingerprint:
          type: string
          title: Block Execution Fingerprint
        execution_fingerprint:
          type: string
          title: Execution Fingerprint
        block_config:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Block Config
          description: The draft block config used for this block execution
        source_step_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Step Id
          description: >-
            The step ID that was used for inputs (includes iteration prefix if
            applicable)
        available_iterations:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Available Iterations
          description: When the block has multiple iterations, lists all available ones
      type: object
      required:
        - block_id
        - block_type
        - id
        - lifecycle
        - source_run_id
        - workflow_id
      title: BlockExecution
      description: |-
        The result of executing a single workflow block.

        The execution state is carried by the `lifecycle` field.
    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
    PendingBlockExecutionLifecycle:
      properties:
        status:
          type: string
          const: pending
          title: Status
          default: pending
      type: object
      title: PendingBlockExecutionLifecycle
      description: The execution row exists but has not been dispatched.
    QueuedBlockExecutionLifecycle:
      properties:
        status:
          type: string
          const: queued
          title: Status
          default: queued
      type: object
      title: QueuedBlockExecutionLifecycle
      description: Dispatch has been requested for this execution.
    RunningBlockExecutionLifecycle:
      properties:
        status:
          type: string
          const: running
          title: Status
          default: running
      type: object
      title: RunningBlockExecutionLifecycle
      description: The executor has started this block execution.
    CompletedBlockExecutionLifecycle:
      properties:
        status:
          type: string
          const: completed
          title: Status
          default: completed
      type: object
      title: CompletedBlockExecutionLifecycle
      description: 'Terminal: the executed block executed successfully.'
    ErrorBlockExecutionLifecycle:
      properties:
        status:
          type: string
          const: error
          title: Status
          default: error
        message:
          type: string
          title: Message
          description: Human-readable error message
      type: object
      required:
        - message
      title: ErrorBlockExecutionLifecycle
      description: |-
        Terminal: the executed block raised. `message` is the executor's
        error string.
    CancelledBlockExecutionLifecycle:
      properties:
        status:
          type: string
          const: cancelled
          title: Status
          default: cancelled
        reason:
          title: Reason
          default: null
      type: object
      title: CancelledBlockExecutionLifecycle
      description: The execution was intentionally stopped before completion.
    SkippedBlockExecutionLifecycle:
      properties:
        status:
          type: string
          const: skipped
          title: Status
          default: skipped
        reason:
          type: string
          title: Reason
          description: Reason the block was skipped
      type: object
      required:
        - reason
      title: SkippedBlockExecutionLifecycle
      description: |-
        Terminal: the block declared its inputs unsatisfied via
        `should_skip_block` and was skipped. `reason` is the skip rationale
        surfaced by the block's input requirements registry.
    BlockExecJsonHandleInput:
      properties:
        data:
          title: Data
          default: null
        type:
          type: string
          const: json
          title: Type
          default: json
      additionalProperties: false
      type: object
      title: BlockExecJsonHandleInput
    BlockExecFileHandleInput:
      properties:
        document:
          $ref: '#/components/schemas/BlockExecFileRef'
        type:
          type: string
          const: file
          title: Type
          default: file
      additionalProperties: false
      type: object
      required:
        - document
      title: BlockExecFileHandleInput
    StepArtifactRef:
      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 kind of resource this artifact references
        id:
          type: string
          title: Id
          description: Resource identifier
      type: object
      required:
        - id
        - operation
      title: StepArtifactRef
      description: >-
        A resource produced by a workflow step.


        An `(operation, id)` reference. The artifact itself carries no payload —

        consumers dispatch on `operation` and fetch the referenced record by
        `id`.
    BlockExecFileRef:
      properties:
        id:
          type: string
          title: Id
          description: ID of the file
        filename:
          type: string
          title: Filename
          description: Filename of the file
        mime_type:
          type: string
          title: Mime Type
          description: MIME type of the file
      type: object
      required:
        - filename
        - id
        - mime_type
      title: BlockExecFileRef
      description: Public/shared file reference used across SDK and customer-facing APIs.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````