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

# Get a turn

> Get a single turn by ID from Redis.



## OpenAPI

````yaml /gateway-agent-harness-openapi.json get /v1/agents/sessions/{sessionId}/turns/{turnId}
openapi: 3.1.0
info:
  title: TrueFoundry Agent Harness
  description: Stateful agent execution API.
  version: 0.1.0
servers:
  - url: '{scheme}://{gatewayBaseURL}/{tenantName}'
    variables:
      scheme:
        default: https
        enum:
          - http
          - https
      gatewayBaseURL:
        default: gateway.truefoundry.ai
        description: Gateway host. Override for self-hosted deployments.
      tenantName:
        default: truefoundry
        description: Tenant identifier
    description: Gateway base URL (per-tenant)
security:
  - AuthorizationBearer: []
paths:
  /v1/agents/sessions/{sessionId}/turns/{turnId}:
    get:
      tags:
        - Agent Harness
      summary: Get a turn
      description: Get a single turn by ID from Redis.
      parameters:
        - schema:
            type: string
            minLength: 1
            description: Session identifier (<ulid>.<zone>).
            example: 01arz3ndektsv4rrffq69g5fav.g
          required: true
          name: sessionId
          in: path
        - schema:
            type: string
            minLength: 1
            description: Turn identifier (<ulid>.<zone>.<executor>).
            example: 01arz3ndektsv4rrffq69g5fav.g.ab12cd
          required: true
          name: turnId
          in: path
      responses:
        '200':
          description: Turn data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTurnResponse'
        '400':
          description: Redis store unavailable or invalid session id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestErrorResponse'
        '404':
          description: Turn not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestErrorResponse'
components:
  schemas:
    GetTurnResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Turn'
      required:
        - data
    RequestErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            code:
              type:
                - string
                - 'null'
            param:
              type:
                - string
                - 'null'
          required:
            - message
      required:
        - error
    Turn:
      type: object
      properties:
        id:
          type: string
        session_id:
          type: string
        previous_turn_id:
          type:
            - string
            - 'null'
        input:
          type: array
          items:
            $ref: '#/components/schemas/TurnInputItem'
        state:
          $ref: '#/components/schemas/TurnState'
        created_by_subject:
          $ref: '#/components/schemas/Subject'
        created_at:
          type: string
      required:
        - id
        - session_id
        - previous_turn_id
        - state
        - created_by_subject
        - created_at
    TurnInputItem:
      oneOf:
        - $ref: '#/components/schemas/UserMessage'
        - $ref: '#/components/schemas/UserToolApprovalEvent'
        - $ref: '#/components/schemas/UserToolResponseEvent'
      discriminator:
        propertyName: type
        mapping:
          user.message:
            $ref: '#/components/schemas/UserMessage'
          user.tool_approval:
            $ref: '#/components/schemas/UserToolApprovalEvent'
          user.tool_response:
            $ref: '#/components/schemas/UserToolResponseEvent'
    TurnState:
      oneOf:
        - $ref: '#/components/schemas/TurnStateRunning'
        - $ref: '#/components/schemas/TurnStateDone'
        - $ref: '#/components/schemas/TurnStateCancelled'
        - $ref: '#/components/schemas/TurnStateError'
      discriminator:
        propertyName: status
        mapping:
          running:
            $ref: '#/components/schemas/TurnStateRunning'
          done:
            $ref: '#/components/schemas/TurnStateDone'
          cancelled:
            $ref: '#/components/schemas/TurnStateCancelled'
          error:
            $ref: '#/components/schemas/TurnStateError'
    Subject:
      type: object
      properties:
        subject_id:
          type: string
        subject_type:
          type: string
        subject_slug:
          type:
            - string
            - 'null'
      required:
        - subject_id
        - subject_type
    UserMessage:
      type: object
      properties:
        type:
          type: string
          enum:
            - user.message
        content:
          anyOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/UserMessageContentItem'
      required:
        - type
        - content
    UserToolApprovalEvent:
      type: object
      properties:
        type:
          type: string
          enum:
            - user.tool_approval
        thread_id:
          type: string
          minLength: 1
        tool_call_id:
          type: string
          minLength: 1
        approval:
          $ref: '#/components/schemas/ApprovalDecision'
      required:
        - type
        - thread_id
        - tool_call_id
        - approval
    UserToolResponseEvent:
      type: object
      properties:
        type:
          type: string
          enum:
            - user.tool_response
        thread_id:
          type: string
          minLength: 1
        tool_call_id:
          type: string
          minLength: 1
        content:
          type: string
          minLength: 1
      required:
        - type
        - thread_id
        - tool_call_id
        - content
    TurnStateRunning:
      type: object
      properties:
        status:
          type: string
          enum:
            - running
      required:
        - status
    TurnStateDone:
      type: object
      properties:
        status:
          type: string
          enum:
            - done
        output:
          allOf:
            - $ref: '#/components/schemas/ModelMessageEvent'
            - type:
                - object
                - 'null'
        required_actions:
          type: array
          items:
            $ref: '#/components/schemas/ActionRequiredEvent'
        completed_at:
          type: string
      required:
        - status
        - output
        - required_actions
        - completed_at
    TurnStateCancelled:
      type: object
      properties:
        status:
          type: string
          enum:
            - cancelled
        reason:
          $ref: '#/components/schemas/TurnStateCancelledReason'
        completed_at:
          type: string
      required:
        - status
        - reason
        - completed_at
    TurnStateError:
      type: object
      properties:
        status:
          type: string
          enum:
            - error
        message:
          type: string
        completed_at:
          type: string
      required:
        - status
        - message
        - completed_at
    UserMessageContentItem:
      oneOf:
        - $ref: '#/components/schemas/TextContent'
        - $ref: '#/components/schemas/FileContent'
      discriminator:
        propertyName: type
        mapping:
          text:
            $ref: '#/components/schemas/TextContent'
          file:
            $ref: '#/components/schemas/FileContent'
    ApprovalDecision:
      oneOf:
        - $ref: '#/components/schemas/ApprovalAllow'
        - $ref: '#/components/schemas/ApprovalDeny'
      discriminator:
        propertyName: status
        mapping:
          allow:
            $ref: '#/components/schemas/ApprovalAllow'
          deny:
            $ref: '#/components/schemas/ApprovalDeny'
    ModelMessageEvent:
      type: object
      properties:
        content:
          anyOf:
            - type: string
            - type: array
              items:
                anyOf:
                  - $ref: '#/components/schemas/ChatCompletionContentPartText'
                  - $ref: '#/components/schemas/ChatCompletionContentPartRefusal'
            - type: 'null'
        name:
          type: string
        refusal:
          type:
            - string
            - 'null'
        reasoning_content:
          type: string
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ToolCall'
        type:
          type: string
          enum:
            - model.message
        id:
          type: string
          description: Unique identifier for the event
        thread_id:
          type: string
        finish_reason:
          $ref: '#/components/schemas/FinishReason'
        created_at:
          type: string
        usage:
          $ref: '#/components/schemas/ModelMessageUsage'
      required:
        - type
        - id
        - thread_id
        - created_at
    ActionRequiredEvent:
      oneOf:
        - $ref: '#/components/schemas/ToolApprovalRequiredEvent'
        - $ref: '#/components/schemas/ToolResponseRequiredEvent'
        - $ref: '#/components/schemas/MCPAuthRequiredEvent'
      discriminator:
        propertyName: type
        mapping:
          tool.approval_required:
            $ref: '#/components/schemas/ToolApprovalRequiredEvent'
          tool.response_required:
            $ref: '#/components/schemas/ToolResponseRequiredEvent'
          mcp.auth_required:
            $ref: '#/components/schemas/MCPAuthRequiredEvent'
    TurnStateCancelledReason:
      type: string
      enum:
        - server-execution-timeout
        - client-cancelled
        - cancelled-for-next-turn
      description: Reason for the cancellation.
    TextContent:
      type: object
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
      required:
        - type
        - text
    FileContent:
      type: object
      properties:
        type:
          type: string
          enum:
            - file
        name:
          type: string
        data:
          type: string
          description: >-
            Data URI: `data:<mime>;base64,<payload>`. MIME type is parsed from
            the URI.
      required:
        - type
        - name
        - data
    ApprovalAllow:
      type: object
      properties:
        status:
          type: string
          enum:
            - allow
      required:
        - status
    ApprovalDeny:
      type: object
      properties:
        status:
          type: string
          enum:
            - deny
        reason:
          type: string
      required:
        - status
    ChatCompletionContentPartText:
      type: object
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
      required:
        - type
        - text
    ChatCompletionContentPartRefusal:
      type: object
      properties:
        type:
          type: string
          enum:
            - refusal
        refusal:
          type: string
      required:
        - type
        - refusal
    ToolCall:
      allOf:
        - $ref: '#/components/schemas/RawToolCall'
        - type: object
          properties:
            tool_info:
              $ref: '#/components/schemas/ToolInfo'
          required:
            - tool_info
    FinishReason:
      type:
        - string
        - 'null'
      enum:
        - stop
        - length
        - tool_calls
        - content_filter
        - function_call
    ModelMessageUsage:
      type: object
      properties:
        input_tokens:
          type: integer
          minimum: 0
        output_tokens:
          type: integer
          minimum: 0
        cache_read_tokens:
          type: integer
          minimum: 0
        cache_write_tokens:
          type: integer
          minimum: 0
        input_tokens_breakdown:
          type: object
          properties:
            harness:
              type: integer
              minimum: 0
            skills:
              type: integer
              minimum: 0
            instructions:
              type: integer
              minimum: 0
            tool_definitions:
              type: integer
              minimum: 0
            messages:
              type: integer
              minimum: 0
          required:
            - harness
            - skills
            - instructions
            - tool_definitions
            - messages
      required:
        - input_tokens
        - output_tokens
        - input_tokens_breakdown
    ToolApprovalRequiredEvent:
      type: object
      properties:
        type:
          type: string
          enum:
            - tool.approval_required
        id:
          type: string
          description: Unique identifier for the event
        created_at:
          type: string
        thread_id:
          type: string
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ToolCallRef'
      required:
        - type
        - id
        - created_at
        - thread_id
        - tool_calls
    ToolResponseRequiredEvent:
      type: object
      properties:
        type:
          type: string
          enum:
            - tool.response_required
        id:
          type: string
          description: Unique identifier for the event
        created_at:
          type: string
        thread_id:
          type: string
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ToolCallRef'
      required:
        - type
        - id
        - created_at
        - thread_id
        - tool_calls
    MCPAuthRequiredEvent:
      allOf:
        - $ref: '#/components/schemas/BaseMCPAuthRequiredEvent'
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp.auth_required
            mcp_servers:
              type: array
              items:
                $ref: '#/components/schemas/MCPServerAuthInfo'
          required:
            - type
            - mcp_servers
    RawToolCall:
      allOf:
        - $ref: '#/components/schemas/ChatCompletionMessageToolCall'
        - type: object
          properties:
            provider_specific_fields:
              type: object
              additionalProperties: {}
    ToolInfo:
      oneOf:
        - $ref: '#/components/schemas/TrueFoundrySystemToolInfo'
        - $ref: '#/components/schemas/MCPToolInfo'
      discriminator:
        propertyName: type
        mapping:
          truefoundry-system:
            $ref: '#/components/schemas/TrueFoundrySystemToolInfo'
          mcp:
            $ref: '#/components/schemas/MCPToolInfo'
    ToolCallRef:
      type: object
      properties:
        id:
          type: string
        source_event_id:
          type: string
      required:
        - id
        - source_event_id
    BaseMCPAuthRequiredEvent:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the event
        created_at:
          type: string
        thread_id:
          type:
            - string
            - 'null'
      required:
        - id
        - created_at
        - thread_id
    MCPServerAuthInfo:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        auth_url:
          type: string
      required:
        - id
        - name
        - auth_url
    ChatCompletionMessageToolCall:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - function
        function:
          type: object
          properties:
            name:
              type: string
            arguments:
              type: string
          required:
            - name
            - arguments
      required:
        - id
        - type
        - function
    TrueFoundrySystemToolInfo:
      type: object
      properties:
        type:
          type: string
          enum:
            - truefoundry-system
        name:
          type: string
      required:
        - type
        - name
    MCPToolInfo:
      type: object
      properties:
        type:
          type: string
          enum:
            - mcp
        server_id:
          type: string
        server_name:
          type: string
        name:
          type: string
      required:
        - type
        - server_id
        - server_name
        - name
  securitySchemes:
    AuthorizationBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````