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

# List turns

> Returns turns newest first. Use the returned next_before_turn_sequence as before_turn_sequence to fetch older turns.



## OpenAPI

````yaml /api-reference/openapi.yaml get /orgs/{orgID}/projects/{projectID}/agents/{agentID}/turns
openapi: 3.1.2
info:
  title: Omnara API
  version: 0.1.0
  description: Public HTTP API contract for Omnara.
servers:
  - url: https://api.omnara.com/v1
    description: Hosted Omnara
security:
  - bearerAuth: []
  - browserSessionCookie: []
tags:
  - name: Agents
    description: >-
      Launch agents, send inputs, manage the input backlog, and work with tool
      calls.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/agents/overview
  - name: Interactions
    description: List and resolve the approvals and questions that pause an agent.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/events/interactions
  - name: Actors
    description: Attribute agent inputs and interaction responses to external users.
    externalDocs:
      description: Guide
      url: >-
        https://docs.omnara.com/events/sending-input#who-said-that-actors-and-attribution
  - name: Events
    description: Read or stream the agent timeline, list turns, and download artifacts.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/events/streaming
  - name: Configs and Profiles
    description: >-
      Create agent configs, manage reusable launch profiles, and set up
      integrations.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/agents/configuration
  - name: Models
    description: Configure model providers and models, and grant projects access to them.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/organization/model-providers
  - name: Machines
    description: Register machines, control project access, and manage daemon tokens.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/machines/connect
  - name: Machine Pools
    description: Define machine pools and grant projects access to them.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/machines/pools
  - name: Secrets
    description: >-
      Manage secret ownership and versions, and inspect or grant project
      availability.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/organization/secrets
  - name: Skills
    description: Manage versioned skill ownership and load skill instructions on demand.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/tools/skills
  - name: Organizations and Projects
    description: Create organizations and projects and manage membership.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/organization/members
  - name: Users and API Keys
    description: >-
      The authenticated user, personal and organization API keys, and
      invitations.
    externalDocs:
      description: Guide
      url: https://docs.omnara.com/api/authentication
  - name: Machine Daemon
    description: Routes the Omnara machine daemon uses to connect a machine.
paths:
  /orgs/{orgID}/projects/{projectID}/agents/{agentID}/turns:
    parameters:
      - name: orgID
        in: path
        required: true
        schema:
          type: string
          pattern: ^org_[a-z2-7]{26}$
      - name: projectID
        in: path
        required: true
        schema:
          type: string
          pattern: ^proj_[a-z2-7]{26}$
      - name: agentID
        in: path
        required: true
        schema:
          type: string
          pattern: ^agt_[a-z2-7]{26}$
    get:
      tags:
        - Events
      summary: List turns
      description: >-
        Returns turns newest first. Use the returned next_before_turn_sequence
        as before_turn_sequence to fetch older turns.
      operationId: listTurns
      parameters:
        - name: before_turn_sequence
          in: query
          required: false
          description: >-
            Exclusive turn sequence boundary. Omit or pass 0 for the newest
            turns.
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: limit
          in: query
          required: false
          description: Maximum number of turns to return.
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 25
      responses:
        '200':
          description: Agent turns.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAgentTurnsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    ListAgentTurnsResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - next_before_turn_sequence
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AgentTurn'
        next_before_turn_sequence:
          anyOf:
            - $ref: '#/components/schemas/AgentSequenceCursor'
            - type: 'null'
          description: >-
            Pass this value as before_turn_sequence to fetch older turns, or
            null when this page reached the beginning of the agent's turns.
    AgentTurn:
      type: object
      additionalProperties: false
      required:
        - id
        - agent_id
        - turn_sequence
        - event_count
        - opening_events
        - started_at
        - updated_at
      properties:
        id:
          $ref: '#/components/schemas/AgentTurnID'
        agent_id:
          $ref: '#/components/schemas/AgentID'
        turn_sequence:
          $ref: '#/components/schemas/AgentSequence'
        event_count:
          $ref: '#/components/schemas/AgentCount'
        opening_events:
          type: array
          items:
            $ref: '#/components/schemas/AgentEvent'
        latest_event:
          $ref: '#/components/schemas/AgentEvent'
        latest_semantic_event:
          $ref: '#/components/schemas/AgentEvent'
        started_at:
          $ref: '#/components/schemas/Timestamp'
        updated_at:
          $ref: '#/components/schemas/Timestamp'
    AgentSequenceCursor:
      description: Non-negative agent timeline cursor.
      type: integer
      minimum: 0
      maximum: 9007199254740991
      x-go-type: int64
    Error:
      type: object
      additionalProperties: false
      required:
        - error
        - code
      properties:
        error:
          type: string
          description: Human-readable error message. Do not match on it programmatically.
        code:
          type: string
          description: Stable error code for programmatic handling.
          enum:
            - invalid_request
            - unauthorized
            - forbidden
            - not_found
            - conflict
            - gone
            - request_too_large
            - unsupported_media_type
            - unprocessable
            - rate_limited
            - internal_error
            - upstream_error
            - service_unavailable
            - idempotency_key_conflict
            - state_transition_conflict
            - managed_work_admission_denied
            - pending_work
            - not_wake_capable
            - daemon_runtime_unregistered
            - validation_failed
            - csrf_check_failed
            - authentication_unavailable
    ClientErrorCode:
      type: string
      description: >-
        Stable error code carried by 4XX statuses. Subset of the Error code enum
        whose statuses are client errors.
      enum:
        - invalid_request
        - validation_failed
        - unauthorized
        - forbidden
        - csrf_check_failed
        - not_found
        - conflict
        - idempotency_key_conflict
        - state_transition_conflict
        - pending_work
        - not_wake_capable
        - gone
        - daemon_runtime_unregistered
        - request_too_large
        - unsupported_media_type
        - unprocessable
        - rate_limited
    ServerErrorCode:
      type: string
      description: >-
        Stable error code carried by 5XX statuses. Subset of the Error code enum
        whose statuses are server errors.
      enum:
        - internal_error
        - upstream_error
        - service_unavailable
        - authentication_unavailable
    AgentTurnID:
      type: string
      pattern: ^trn_[a-z2-7]{26}$
    AgentID:
      type: string
      pattern: ^agt_[a-z2-7]{26}$
    AgentSequence:
      description: Positive per-agent event, turn, or live-frame sequence.
      type: integer
      minimum: 1
      maximum: 9007199254740991
      x-go-type: int64
    AgentCount:
      description: Positive count within an agent timeline.
      type: integer
      minimum: 1
      maximum: 9007199254740991
      x-go-type: int64
    AgentEvent:
      oneOf:
        - $ref: '#/components/schemas/AgentInputEvent'
        - $ref: '#/components/schemas/ModelOutputEvent'
        - $ref: '#/components/schemas/ToolResultEvent'
        - $ref: '#/components/schemas/ContextCheckpointEvent'
      discriminator:
        propertyName: event_kind
        mapping:
          agent_input:
            $ref: '#/components/schemas/AgentInputEvent'
          model_output:
            $ref: '#/components/schemas/ModelOutputEvent'
          tool_result:
            $ref: '#/components/schemas/ToolResultEvent'
          context_checkpoint:
            $ref: '#/components/schemas/ContextCheckpointEvent'
    Timestamp:
      type: string
      format: date-time
    AgentInputEvent:
      type: object
      additionalProperties: false
      required:
        - id
        - org_id
        - project_id
        - agent_id
        - turn_id
        - turn_sequence
        - is_opening_event
        - sequence
        - event_kind
        - agent_input_id
        - input_kind
        - content_blocks
        - created_at
      properties:
        id:
          $ref: '#/components/schemas/AgentEventID'
        org_id:
          $ref: '#/components/schemas/OrganizationID'
        project_id:
          $ref: '#/components/schemas/ProjectID'
        agent_id:
          $ref: '#/components/schemas/AgentID'
        turn_id:
          $ref: '#/components/schemas/AgentTurnID'
        turn_sequence:
          $ref: '#/components/schemas/AgentSequence'
        is_opening_event:
          type: boolean
        sequence:
          $ref: '#/components/schemas/AgentSequence'
        event_kind:
          type: string
          enum:
            - agent_input
        agent_input_id:
          $ref: '#/components/schemas/AgentInputID'
          description: >-
            Matches the input that produced this event, allowing clients to
            correlate an input submission with its durable timeline admission.
        input_kind:
          $ref: '#/components/schemas/AgentInputKind'
        actor_id:
          $ref: '#/components/schemas/ActorID'
          description: >-
            Actor attributed to the input. Resolve details through the project
            actors endpoints.
        input_idempotency_key:
          type: string
          description: >-
            Echoes the Idempotency-Key of a content-input request so its sender
            can recognize the durable admission. Absent for other input kinds.
        control_type:
          $ref: '#/components/schemas/AgentControlType'
        interaction_id:
          $ref: '#/components/schemas/AgentInteractionID'
          description: Interaction answered by an interaction_response input.
        agent_config_id:
          $ref: '#/components/schemas/AgentConfigID'
          description: Configuration selected by a config_change input.
        content_blocks:
          type: array
          items:
            $ref: '#/components/schemas/AgentInputContentBlock'
        created_at:
          $ref: '#/components/schemas/Timestamp'
    ModelOutputEvent:
      type: object
      additionalProperties: false
      required:
        - id
        - org_id
        - project_id
        - agent_id
        - turn_id
        - turn_sequence
        - is_opening_event
        - sequence
        - event_kind
        - model_call_context_id
        - stop_reason
        - content_blocks
        - created_at
      properties:
        id:
          $ref: '#/components/schemas/AgentEventID'
        org_id:
          $ref: '#/components/schemas/OrganizationID'
        project_id:
          $ref: '#/components/schemas/ProjectID'
        agent_id:
          $ref: '#/components/schemas/AgentID'
        turn_id:
          $ref: '#/components/schemas/AgentTurnID'
        turn_sequence:
          $ref: '#/components/schemas/AgentSequence'
        is_opening_event:
          type: boolean
          enum:
            - false
          x-enum-varnames:
            - ModelOutputEventIsOpeningEventFalse
        sequence:
          $ref: '#/components/schemas/AgentSequence'
        event_kind:
          type: string
          enum:
            - model_output
        model_call_context_id:
          $ref: '#/components/schemas/ModelCallContextID'
        stop_reason:
          $ref: '#/components/schemas/ModelOutputStopReason'
        content_blocks:
          type: array
          items:
            $ref: '#/components/schemas/ModelOutputContentBlock'
        created_at:
          $ref: '#/components/schemas/Timestamp'
    ToolResultEvent:
      type: object
      additionalProperties: false
      required:
        - id
        - org_id
        - project_id
        - agent_id
        - turn_id
        - turn_sequence
        - is_opening_event
        - sequence
        - event_kind
        - tool_call_id
        - outcome
        - content_blocks
        - created_at
      properties:
        id:
          $ref: '#/components/schemas/AgentEventID'
        org_id:
          $ref: '#/components/schemas/OrganizationID'
        project_id:
          $ref: '#/components/schemas/ProjectID'
        agent_id:
          $ref: '#/components/schemas/AgentID'
        turn_id:
          $ref: '#/components/schemas/AgentTurnID'
        turn_sequence:
          $ref: '#/components/schemas/AgentSequence'
        is_opening_event:
          type: boolean
          enum:
            - false
          x-enum-varnames:
            - ToolResultEventIsOpeningEventFalse
        sequence:
          $ref: '#/components/schemas/AgentSequence'
        event_kind:
          type: string
          enum:
            - tool_result
        tool_call_id:
          $ref: '#/components/schemas/ToolCallID'
        outcome:
          $ref: '#/components/schemas/ToolCallOutcome'
        content_blocks:
          type: array
          items:
            $ref: '#/components/schemas/ToolResultContentBlock'
        created_at:
          $ref: '#/components/schemas/Timestamp'
    ContextCheckpointEvent:
      type: object
      additionalProperties: false
      required:
        - id
        - org_id
        - project_id
        - agent_id
        - turn_id
        - turn_sequence
        - is_opening_event
        - sequence
        - event_kind
        - context_checkpoint_id
        - summarized_through_event_sequence
        - summary
        - created_at
      properties:
        id:
          $ref: '#/components/schemas/AgentEventID'
        org_id:
          $ref: '#/components/schemas/OrganizationID'
        project_id:
          $ref: '#/components/schemas/ProjectID'
        agent_id:
          $ref: '#/components/schemas/AgentID'
        turn_id:
          $ref: '#/components/schemas/AgentTurnID'
        turn_sequence:
          $ref: '#/components/schemas/AgentSequence'
        is_opening_event:
          type: boolean
          enum:
            - false
          x-enum-varnames:
            - ContextCheckpointEventIsOpeningEventFalse
        sequence:
          $ref: '#/components/schemas/AgentSequence'
        event_kind:
          type: string
          enum:
            - context_checkpoint
        context_checkpoint_id:
          $ref: '#/components/schemas/ContextCheckpointID'
        summarized_through_event_sequence:
          $ref: '#/components/schemas/AgentSequence'
        summary:
          type: string
        created_at:
          $ref: '#/components/schemas/Timestamp'
    AgentEventID:
      type: string
      pattern: ^evt_[a-z2-7]{26}$
    OrganizationID:
      type: string
      pattern: ^org_[a-z2-7]{26}$
    ProjectID:
      type: string
      pattern: ^proj_[a-z2-7]{26}$
    AgentInputID:
      type: string
      pattern: ^ain_[a-z2-7]{26}$
    AgentInputKind:
      type: string
      enum:
        - content
        - control
        - interaction_response
        - config_change
      x-enum-varnames:
        - AgentInputKindContent
        - AgentInputKindControl
        - AgentInputKindInteractionResponse
        - AgentInputKindConfigChange
    ActorID:
      type: string
      pattern: ^actr_[a-z2-7]{26}$
    AgentControlType:
      type: string
      enum:
        - cancel_current
      x-enum-varnames:
        - AgentControlTypeCancelCurrent
    AgentInteractionID:
      type: string
      pattern: ^int_[a-z2-7]{26}$
    AgentConfigID:
      type: string
      pattern: ^acfg_[a-z2-7]{26}$
    AgentInputContentBlock:
      oneOf:
        - $ref: '#/components/schemas/TextContentBlock'
        - $ref: '#/components/schemas/MediaRefContentBlock'
      discriminator:
        propertyName: type
        mapping:
          text:
            $ref: '#/components/schemas/TextContentBlock'
          media_ref:
            $ref: '#/components/schemas/MediaRefContentBlock'
    ModelCallContextID:
      type: string
      pattern: ^mcc_[a-z2-7]{26}$
    ModelOutputStopReason:
      description: Stop reasons admitted as durable model-output events.
      type: string
      enum:
        - end_turn
        - tool_use
        - max_tokens
        - refusal
        - content_filter
        - error
      x-enum-varnames:
        - ModelOutputStopReasonEndTurn
        - ModelOutputStopReasonToolUse
        - ModelOutputStopReasonMaxTokens
        - ModelOutputStopReasonRefusal
        - ModelOutputStopReasonContentFilter
        - ModelOutputStopReasonError
    ModelOutputContentBlock:
      oneOf:
        - $ref: '#/components/schemas/TextContentBlock'
        - $ref: '#/components/schemas/MediaRefContentBlock'
        - $ref: '#/components/schemas/ReasoningContentBlock'
        - $ref: '#/components/schemas/ModelToolCallContentBlock'
        - $ref: '#/components/schemas/ErrorContentBlock'
      discriminator:
        propertyName: type
        mapping:
          text:
            $ref: '#/components/schemas/TextContentBlock'
          media_ref:
            $ref: '#/components/schemas/MediaRefContentBlock'
          reasoning:
            $ref: '#/components/schemas/ReasoningContentBlock'
          tool_call:
            $ref: '#/components/schemas/ModelToolCallContentBlock'
          error:
            $ref: '#/components/schemas/ErrorContentBlock'
    ToolCallID:
      type: string
      pattern: ^tcl_[a-z2-7]{26}$
    ToolCallOutcome:
      description: Terminal outcome, present only when state is completed.
      type: string
      enum:
        - succeeded
        - failed
        - denied
        - canceled
      x-enum-varnames:
        - ToolCallOutcomeSucceeded
        - ToolCallOutcomeFailed
        - ToolCallOutcomeDenied
        - ToolCallOutcomeCanceled
    ToolResultContentBlock:
      oneOf:
        - $ref: '#/components/schemas/TextContentBlock'
        - $ref: '#/components/schemas/MediaRefContentBlock'
        - $ref: '#/components/schemas/StructuredDataContentBlock'
      discriminator:
        propertyName: type
        mapping:
          text:
            $ref: '#/components/schemas/TextContentBlock'
          media_ref:
            $ref: '#/components/schemas/MediaRefContentBlock'
          structured_data:
            $ref: '#/components/schemas/StructuredDataContentBlock'
    ContextCheckpointID:
      type: string
      pattern: ^ccp_[a-z2-7]{26}$
    TextContentBlock:
      type: object
      additionalProperties: false
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
        metadata:
          $ref: '#/components/schemas/ContentBlockMetadata'
    MediaRefContentBlock:
      type: object
      additionalProperties: false
      required:
        - type
        - artifact_id
      properties:
        type:
          type: string
          enum:
            - media_ref
        artifact_id:
          $ref: '#/components/schemas/ArtifactID'
        metadata:
          $ref: '#/components/schemas/ContentBlockMetadata'
    ReasoningContentBlock:
      type: object
      additionalProperties: false
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - reasoning
        text:
          type: string
        metadata:
          $ref: '#/components/schemas/ContentBlockMetadata'
    ModelToolCallContentBlock:
      type: object
      additionalProperties: false
      required:
        - type
        - tool_call_id
        - tool_type
        - name
        - input
      properties:
        type:
          type: string
          enum:
            - tool_call
        tool_call_id:
          $ref: '#/components/schemas/ToolCallID'
        tool_type:
          $ref: '#/components/schemas/ToolCallType'
        name:
          type: string
        input:
          $ref: '#/components/schemas/ToolInput'
        metadata:
          $ref: '#/components/schemas/ContentBlockMetadata'
    ErrorContentBlock:
      type: object
      additionalProperties: false
      required:
        - type
        - text
      properties:
        type:
          type: string
          enum:
            - error
        text:
          type: string
        metadata:
          $ref: '#/components/schemas/ContentBlockMetadata'
    StructuredDataContentBlock:
      type: object
      additionalProperties: false
      required:
        - type
        - value
      properties:
        type:
          type: string
          enum:
            - structured_data
        value:
          $ref: '#/components/schemas/JSONBlob'
        metadata:
          $ref: '#/components/schemas/ContentBlockMetadata'
    ContentBlockMetadata:
      $ref: '#/components/schemas/Metadata'
      description: >-
        Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64
        characters, values must be strings of up to 512 characters. Keys
        beginning with `omnara_` are reserved for Omnara and may affect product
        behavior; use them only when intentionally invoking Omnara-defined
        behavior.
    ArtifactID:
      type: string
      pattern: ^art_[a-z2-7]{26}$
    ToolCallType:
      description: >-
        Identifies who manages execution. Built-in and MCP calls are
        platform-managed; custom calls wait for an external consumer to submit
        their result.
      type: string
      enum:
        - built_in
        - custom
        - mcp
      x-enum-varnames:
        - ToolCallTypeBuiltIn
        - ToolCallTypeCustom
        - ToolCallTypeMCP
    ToolInput:
      description: Non-null JSON object containing the arguments emitted for a tool call.
      type: object
      additionalProperties: true
      x-go-type: json.RawMessage
      x-go-type-skip-optional-pointer: true
    JSONBlob:
      description: >-
        Public JSON payload whose shape is determined by the event or
        interaction kind.
    Metadata:
      type: object
      description: >-
        Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64
        characters, values must be strings of up to 512 characters.
      x-go-type: resourcemeta.Metadata
      x-go-type-import:
        path: github.com/omnara-ai/omnara/internal/resourcemeta
      x-go-type-skip-optional-pointer: true
      maxProperties: 16
      propertyNames:
        minLength: 1
        maxLength: 64
      additionalProperties:
        type: string
        maxLength: 512
  responses:
    BadRequest:
      description: The request was invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication is required or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The authenticated principal is not authorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found or is not visible.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: The service dependency required to satisfy the request is unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ClientError:
      description: >-
        Any other client error. The body carries the shared Error envelope
        restricted to client error codes; statuses with a dedicated response
        above are documented precisely.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            required:
              - error
              - code
            properties:
              error:
                type: string
                description: >-
                  Human-readable error message. Do not match on it
                  programmatically.
              code:
                $ref: '#/components/schemas/ClientErrorCode'
    ServerError:
      description: >-
        Any other server error. The body carries the shared Error envelope
        restricted to server error codes.
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            required:
              - error
              - code
            properties:
              error:
                type: string
                description: >-
                  Human-readable error message. Do not match on it
                  programmatically.
              code:
                $ref: '#/components/schemas/ServerErrorCode'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Omnara personal or organization access token
      description: An opaque Omnara personal or organization bearer token.
    browserSessionCookie:
      type: apiKey
      in: cookie
      name: __Host-omnara_session
      description: >-
        Browser session cookie. HTTPS deployments use __Host-omnara_session;
        local HTTP development uses omnara_session.

````