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

# Get an Omni agent run

> Read a queued, running, completed, paused, or failed Omni agent run. Requires `agents:invoke`.



## OpenAPI

````yaml /openapi.json get /api/v1/agents/general/runs/{runId}
openapi: 3.1.0
info:
  title: OmniCommerce API
  version: 1.0.0
  license:
    name: Proprietary
    url: https://omnicommerce.sg/terms
  description: >-
    OmniCommerce API surface for agents and developer integrations. Includes
    public endpoints (merchant discovery, product search, compare, catalog, ACO
    retrieval) and authenticated endpoints (product management via API key
    Bearer tokens).
servers:
  - url: https://omnicommerce.sg
    description: Production
  - url: http://localhost:3000
    description: Local development
security: []
tags:
  - name: agentic-checkout
    description: Merchant-fulfilled agentic checkout
    x-group: Agentic Checkout
  - name: agents
    description: agents
    x-group: Agents
  - name: aops
    description: Agent operating procedures
    x-group: AOPs
  - name: campaigns
    description: Campaign briefs, offer windows, and marketplace runs
    x-group: Campaigns
  - name: commerce
    description: Root commerce discovery
    x-group: Commerce
  - name: developer-platform
    description: Authenticated developer platform APIs
    x-group: Developer Platform
  - name: looks
    description: AI-styled product looks
    x-group: Looks
  - name: oauth
    description: OAuth token endpoints
    x-group: OAuth
  - name: orders
    description: Workspace and agentic orders
    x-group: Orders
  - name: organizations
    description: Organization management
    x-group: Organizations
  - name: price-books
    description: Marketplace list-price markup rules
    x-group: Price Books
  - name: products
    description: Product CRUD, bulk import, enrichment, publish, and delist
    x-group: Products
  - name: promotions
    description: Central promotions and marketplace sync
    x-group: Promotions
  - name: public-agent
    description: Public agent discovery and catalog APIs
    x-group: Public Agent
  - name: returns
    description: returns
    x-group: Returns
  - name: settlements
    description: settlements
    x-group: Settlements
  - name: ucp
    description: Universal Commerce Protocol
    x-group: UCP
paths:
  /api/v1/agents/general/runs/{runId}:
    get:
      tags:
        - agents
      summary: Get an Omni agent run
      description: >-
        Read a queued, running, completed, paused, or failed Omni agent run.
        Requires `agents:invoke`.
      operationId: get_v1_agents_general_runs_by_runid
      parameters:
        - name: runId
          in: path
          required: true
          schema:
            type: string
        - name: organizationId
          in: query
          required: false
          description: >-
            Required for session auth. Optional for API keys, which already
            belong to one organization.
          schema:
            type: string
            maxLength: 120
      responses:
        '200':
          description: The agent run.
          headers:
            Retry-After:
              description: >-
                Seconds to wait before polling again. Sent while the run is
                queued or running.
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                type: object
                properties:
                  run_id:
                    type: string
                  thread_id:
                    type: string
                  status:
                    type: string
                    enum:
                      - queued
                      - running
                      - completed
                      - awaiting_approval
                      - failed
                  messages:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          enum:
                            - human
                            - ai
                            - tool
                            - system
                        role:
                          type: string
                          enum:
                            - user
                            - assistant
                            - tool
                            - system
                        content:
                          type: string
                        id:
                          type: string
                        name:
                          type: string
                        tool_calls:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              name:
                                type: string
                              args: {}
                            required:
                              - name
                              - args
                        tool_call_id:
                          type: string
                      required:
                        - type
                        - role
                        - content
                  structured_output:
                    anyOf:
                      - type: object
                        propertyNames:
                          type: string
                        additionalProperties: {}
                      - type: 'null'
                  approvals:
                    anyOf:
                      - type: array
                        items:
                          type: object
                          properties:
                            interrupt_instance_id:
                              type: string
                            tool_name:
                              anyOf:
                                - type: string
                                - type: 'null'
                            tool_args: {}
                            message:
                              type: string
                          required:
                            - interrupt_instance_id
                            - tool_name
                            - tool_args
                            - message
                      - type: 'null'
                  error:
                    anyOf:
                      - type: string
                      - type: 'null'
                required:
                  - run_id
                  - thread_id
                  - status
                  - messages
                  - structured_output
                  - approvals
                  - error
        '400':
          description: >-
            Invalid agent request, unknown tool or model, or a decision count
            that does not match the pending approvals
        '401':
          description: Unauthorized
        '403':
          description: Missing agents:invoke scope or Assistant access
        '404':
          description: Agent run not found
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Bearer API key for server-to-server access. Session auth is also
        supported in first-party UI flows.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.