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

# Get Step

> Get one step by its step id.

Returns the same step shape as `GET /workflows/steps`.

Get one persisted step object by `step_id`. The response uses the same step
shape as [List Steps](/api-reference/workflows/steps/list): lifecycle, handle
payloads, artifact ref, and timing fields.

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

  client = Retab()

  step = client.workflows.steps.get("step_extract_1")

  print(step.lifecycle.status)
  print(step.handle_outputs)

  if step.handle_outputs:
      payload = step.handle_outputs["output-json-0"]
      print(payload.type)
      print(payload.data)
  ```

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

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

  const step = await client.workflows.steps.get("step_extract_1");

  console.log(`Step status: ${step.lifecycle.status}`);
  const payload = step.handleOutputs["output-json-0"];
  if (payload?.type === "json") {
    console.log(payload.data);
  }
  ```

  ```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)
  	}

  	step, err := client.Workflows.Steps.Get(ctx, "step_extract_1", nil)
  	if err != nil {
  		log.Fatal(err)
  	}

  	fmt.Printf("Step status: %v\n", step.Lifecycle.Status())
  	if payload, ok := step.HandleOutputs["output-json-0"]; ok {
  		fmt.Println(payload.Type)
  		fmt.Println(payload.Data)
  	}
  }
  ```

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

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

  step = client.workflows.steps.get(step_id: 'step_extract_1')

  puts step.lifecycle.status
  puts step.handle_outputs

  if step.handle_outputs
    payload = step.handle_outputs['output-json-0']
    puts payload.type
    puts payload.data
  end
  ```

  ```rust Rust theme={null}
  use retab::resources::workflow_steps::GetParams;
  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 step = client
          .workflows().steps()
          .get("step_extract_1", GetParams::default())
          .await?;

      println!("{:?}", step.lifecycle);
      if let Some(outputs) = &step.handle_outputs {
          if let Some(payload) = outputs.get("output-json-0") {
              println!("{:?}", payload);
          }
      }
      Ok(())
  }
  ```

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

  use Retab\Client;

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

  $result = $client->workflows()->steps()->get(
      stepId: 'step_abc123',
  );
  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.Steps.GetAsync("step_abc123", new WorkflowStepsGetOptions());
  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().steps().get("step_abc123", "run_abc123");
      System.out.println(result);
    }
  }
  ```

  ```curl cURL theme={null}
  curl -X 'GET' \
    'https://api.retab.com/v1/workflows/steps/step_extract_1' \
    -H 'Authorization: Bearer <your-api-key>'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "step_id": "step_extract_1",
    "run_id": "run_abc123xyz",
    "block_id": "extract-block-1",
    "block_type": "extract",
    "block_label": "Extract Invoice",
    "lifecycle": { "status": "completed" },
    "started_at": "2026-05-18T10:00:00Z",
    "completed_at": "2026-05-18T10:00:04Z",
    "loop_containers": [],
    "artifact": { "operation": "extraction", "id": "ext_abc123" },
    "retry_count": 0,
    "created_at": "2026-05-18T10:00:00Z",
    "handle_outputs": {
      "output-json-0": {
        "type": "json",
        "data": {
          "invoice_number": "INV-2024-001",
          "total_amount": 1234.56,
          "vendor_name": "Acme Corp"
        }
      }
    },
    "handle_inputs": {
      "input-file-0": {
        "type": "file",
        "document": {
          "id": "file_123",
          "filename": "invoice.pdf",
          "mime_type": "application/pdf"
        }
      }
    },
    "model": null
  }
  ```

  ```json 200 (failed step) theme={null}
  {
    "step_id": "step_extract_1",
    "run_id": "run_abc123xyz",
    "block_id": "extract-block-1",
    "block_type": "extract",
    "block_label": "Extract Invoice",
    "lifecycle": { "status": "error", "message": "Model request failed" },
    "started_at": "2026-05-18T10:00:00Z",
    "completed_at": "2026-05-18T10:00:04Z",
    "loop_containers": [],
    "artifact": null,
    "retry_count": 0,
    "created_at": "2026-05-18T10:00:00Z",
    "handle_outputs": {},
    "handle_inputs": {},
    "model": null
  }
  ```

  ```json 404 theme={null}
  {
    "detail": "Step 'step_extract_1' not found"
  }
  ```
</ResponseExample>


## OpenAPI

````yaml GET /v1/workflows/steps/{step_id}
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers:
  - url: https://api.retab.com
security: []
paths:
  /v1/workflows/steps/{step_id}:
    get:
      tags:
        - Workflows
        - Workflow Run Steps
      summary: Get Workflow Step
      description: |-
        Get one step by its step id.

        Returns the same step shape as `GET /workflows/steps`.
      operationId: get_workflow_step
      parameters:
        - in: path
          name: step_id
          required: true
          schema:
            type: string
            title: Step Id
        - in: query
          name: run_id
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Optional workflow run ID disambiguator.
            title: Run Id
          required: false
          description: Optional workflow run ID disambiguator.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowStep'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    WorkflowStep:
      properties:
        block_id:
          type: string
          title: Block Id
          description: Logical ID of the block
        step_id:
          type: string
          title: Step Id
          description: >-
            Full step ID with iteration context. Assigned ONCE at creation,
            never recomputed.
        block_type:
          type: string
          enum:
            - start_document
            - start_json
            - note
            - parse
            - edit
            - extract
            - split
            - classifier
            - conditional
            - api_call
            - function
            - while_loop
            - for_each
            - merge_dicts
            - while_loop_sentinel_start
            - while_loop_sentinel_end
            - for_each_sentinel_start
            - for_each_sentinel_end
          title: Block Type
          description: Type of the block
        block_label:
          type: string
          title: Block Label
          description: Label of the block
        lifecycle:
          oneOf:
            - $ref: '#/components/schemas/PendingStepLifecycle'
            - $ref: '#/components/schemas/QueuedStepLifecycle'
            - $ref: '#/components/schemas/RunningStepLifecycle'
            - $ref: '#/components/schemas/CompletedStepLifecycle'
            - $ref: '#/components/schemas/AwaitingReviewStepLifecycle'
            - $ref: '#/components/schemas/ErrorStepLifecycle'
            - $ref: '#/components/schemas/SkippedStepLifecycle'
            - $ref: '#/components/schemas/CancelledStepLifecycle'
          title: Lifecycle
          description: Current step lifecycle
          discriminator:
            propertyName: status
            mapping:
              awaiting_review:
                $ref: '#/components/schemas/AwaitingReviewStepLifecycle'
              cancelled:
                $ref: '#/components/schemas/CancelledStepLifecycle'
              completed:
                $ref: '#/components/schemas/CompletedStepLifecycle'
              error:
                $ref: '#/components/schemas/ErrorStepLifecycle'
              pending:
                $ref: '#/components/schemas/PendingStepLifecycle'
              queued:
                $ref: '#/components/schemas/QueuedStepLifecycle'
              running:
                $ref: '#/components/schemas/RunningStepLifecycle'
              skipped:
                $ref: '#/components/schemas/SkippedStepLifecycle'
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
          description: When the step started executing
        completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Completed At
          description: When the step finished executing
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
          description: LLM model used by this step, when applicable
        loop_containers:
          items:
            $ref: '#/components/schemas/ContainerContextData'
          type: array
          title: Loop Containers
          description: >-
            Container hierarchy from outermost to innermost. Empty when not
            inside any container.
          default: []
        run_id:
          type: string
          title: Run Id
          description: Parent workflow run ID
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
          description: When the step was created
        handle_inputs:
          additionalProperties:
            $ref: '#/components/schemas/PublicHandlePayload'
          type: object
          title: Handle Inputs
          description: Handle input payloads consumed by this step
          default: {}
        handle_outputs:
          additionalProperties:
            $ref: '#/components/schemas/PublicHandlePayload'
          type: object
          title: Handle Outputs
          description: Handle output payloads produced by this step
          default: {}
        artifact:
          anyOf:
            - $ref: '#/components/schemas/StepArtifactRef'
            - type: 'null'
          description: Reference to the result produced by this step, if any.
        retry_count:
          type: integer
          title: Retry Count
          description: Number of retry attempts
          default: 0
      type: object
      required:
        - block_id
        - block_label
        - block_type
        - lifecycle
        - run_id
        - step_id
      title: WorkflowStep
      description: Public step status object.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
          default: []
      type: object
      title: HTTPValidationError
    PendingStepLifecycle:
      properties:
        status:
          type: string
          const: pending
          title: Status
          default: pending
      type: object
      title: PendingStepLifecycle
      description: The step has been created but execution has not started.
    QueuedStepLifecycle:
      properties:
        status:
          type: string
          const: queued
          title: Status
          default: queued
      type: object
      title: QueuedStepLifecycle
      description: The step is queued for execution.
    RunningStepLifecycle:
      properties:
        status:
          type: string
          const: running
          title: Status
          default: running
      type: object
      title: RunningStepLifecycle
      description: The step is currently executing.
    CompletedStepLifecycle:
      properties:
        status:
          type: string
          const: completed
          title: Status
          default: completed
      type: object
      title: CompletedStepLifecycle
      description: The step finished successfully.
    AwaitingReviewStepLifecycle:
      properties:
        status:
          type: string
          const: awaiting_review
          title: Status
          default: awaiting_review
      type: object
      title: AwaitingReviewStepLifecycle
      description: The step is paused on a human review decision.
    ErrorStepLifecycle:
      properties:
        status:
          type: string
          const: error
          title: Status
          default: error
        message:
          type: string
          title: Message
          description: Human-readable error message
        stage:
          anyOf:
            - type: string
              enum:
                - input_collection
                - registry_lookup
                - document_fetch
                - execution
                - output_storage
                - routing
                - history_payload
            - type: 'null'
          title: Stage
        category:
          anyOf:
            - type: string
              enum:
                - transient
                - permanent
                - quota
            - type: 'null'
          title: Category
        details:
          anyOf:
            - $ref: '#/components/schemas/ErrorDetails'
            - type: 'null'
      type: object
      required:
        - message
      title: ErrorStepLifecycle
      description: The step failed. Error details are bundled into lifecycle.
    SkippedStepLifecycle:
      properties:
        status:
          type: string
          const: skipped
          title: Status
          default: skipped
        reason:
          type: string
          title: Reason
          description: Reason the step was skipped
      type: object
      required:
        - reason
      title: SkippedStepLifecycle
      description: The step was skipped.
    CancelledStepLifecycle:
      properties:
        status:
          type: string
          const: cancelled
          title: Status
          default: cancelled
        reason:
          type: string
          title: Reason
          description: Reason the step was cancelled
      type: object
      required:
        - reason
      title: CancelledStepLifecycle
      description: The step was cancelled.
    ContainerContextData:
      properties:
        container_id:
          type: string
          title: Container Id
          description: Container ID (e.g., 'while_loop-abc')
        iteration:
          type: integer
          title: Iteration
          description: Iteration index (0-based)
        is_parallel:
          type: boolean
          title: Is Parallel
          description: Whether this container represents a parallel item
          default: false
        parallel_item_index:
          anyOf:
            - type: integer
            - type: 'null'
          title: Parallel Item Index
          description: Parallel item index if is_parallel
      type: object
      required:
        - container_id
        - iteration
      title: ContainerContextData
      description: Structured context for a single container in the hierarchy.
    PublicHandlePayload:
      properties:
        type:
          type: string
          enum:
            - file
            - json
          title: Type
          description: Type of payload
        document:
          anyOf:
            - $ref: '#/components/schemas/FileRef'
            - type: 'null'
          description: 'For file handles: document reference'
        data:
          title: Data
          description: 'For JSON handles: structured data'
          default: null
      type: object
      required:
        - type
      title: PublicHandlePayload
      description: Public handle payload exposed by workflow step APIs.
    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`.
    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
    ErrorDetails:
      properties:
        message:
          anyOf:
            - type: string
            - type: 'null'
          title: Message
          description: >-
            Human-readable error message. Free-text; the structured fields below
            are the machine-readable counterpart.
        stack_trace:
          anyOf:
            - type: string
            - type: 'null'
          title: Stack Trace
          description: Full stack trace
        block_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Block Id
          description: ID of the block that failed
        block_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Block Name
          description: Name/label of the block that failed
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
          description: Error code if available
        context:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Context
          description: Additional context about the error
      type: object
      title: ErrorDetails
      description: |-
        Detailed error information for debugging.

        Captures stack traces and context about where and why an error occurred.
    FileRef:
      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: FileRef
      description: Public/shared file reference used across SDK and customer-facing APIs.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````