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

# Get a run

> A run's status (queued, running, succeeded, partial, failed, cancelled), counts, credits (unit price, quoted, held, charged) and a page of its items with their outputs. Poll every 10–30 seconds until the status is terminal.



## OpenAPI

````yaml get /api/v2/runs/{oId}
openapi: 3.0.0
info:
  version: 6.0.0
  title: Octave API
  description: API for Octave workspace management and AI-powered content generation
servers:
  - url: https://app.octavehq.com
security:
  - ApiKeyAuth: []
paths:
  /api/v2/runs/{oId}:
    get:
      tags:
        - Run
      summary: Get a run
      description: >-
        A run's status (queued, running, succeeded, partial, failed, cancelled),
        counts, credits (unit price, quoted, held, charged) and a page of its
        items with their outputs. Poll every 10–30 seconds until the status is
        terminal.
      operationId: getRun
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 64
            description: The run's oId (run_ prefix), from the start call.
            example: run_3rgkoHhR00cEdE9DjKeIK
          required: true
          description: The run's oId (run_ prefix), from the start call.
          name: oId
          in: path
        - schema:
            type: integer
            nullable: true
            minimum: 0
            default: 0
            description: Items to skip, in item order.
          required: false
          description: Items to skip, in item order.
          name: itemsOffset
          in: query
        - schema:
            type: integer
            nullable: true
            minimum: 0
            maximum: 100
            default: 50
            description: Items to return (0–100).
          required: false
          description: Items to return (0–100).
          name: itemsLimit
          in: query
      responses:
        '200':
          description: The run and a page of its items
          content:
            application/json:
              schema:
                type: object
                properties:
                  _metadata:
                    $ref: '#/components/schemas/Metadata'
                  run:
                    $ref: '#/components/schemas/Run'
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/RunItem'
                    description: >-
                      A page of the run's items in order: each item's values,
                      status, output (a skill item's Asset link), credits and
                      error.
                  itemsTotal:
                    type: integer
                    description: Every item of the run, of which `items` is one page.
                  hasNext:
                    type: boolean
                    description: Whether more items follow this page.
                required:
                  - _metadata
                  - run
                  - items
                  - itemsTotal
                  - hasNext
        '404':
          description: No such run in this workspace
          content:
            application/json:
              schema:
                type: object
                properties:
                  _metadata:
                    $ref: '#/components/schemas/Metadata'
                  message:
                    type: string
                required:
                  - _metadata
                  - message
      deprecated: false
components:
  schemas:
    Metadata:
      type: object
      properties:
        usage:
          type: number
          default: 0
          example: 0
          description: API usage
        requestId:
          type: string
          example: requestId
          description: Request ID
        message:
          type: string
          example: message
          description: Message
        timestamp:
          type: string
          example: '2021-01-01T00:00:00.000Z'
          description: Timestamp
      required:
        - requestId
        - timestamp
    Run:
      type: object
      properties:
        oId:
          type: string
        subject:
          oneOf:
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - skill
                skill:
                  oneOf:
                    - type: object
                      properties:
                        source:
                          type: string
                          enum:
                            - catalog
                        name:
                          type: string
                          minLength: 1
                          maxLength: 64
                          pattern: ^[a-z0-9][a-z0-9-]*$
                      required:
                        - source
                        - name
                      additionalProperties: false
                    - type: object
                      properties:
                        source:
                          type: string
                          enum:
                            - workspace
                        skillOId:
                          type: string
                          minLength: 1
                          maxLength: 64
                      required:
                        - source
                        - skillOId
                      additionalProperties: false
                draft:
                  type: boolean
              required:
                - kind
                - skill
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - prioritized_abm
                loopRunOId:
                  type: string
                  minLength: 1
              required:
                - kind
                - loopRunOId
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - deal_deliverable
                opportunityOId:
                  type: string
                  minLength: 1
                deliverable:
                  type: string
                  enum:
                    - account_plan
                    - one_pager
                    - first_call_deck
                    - magazine
                    - follow_up_emails
                    - re_engagement_plan
                actionKey:
                  type: string
              required:
                - kind
                - opportunityOId
                - deliverable
                - actionKey
        subjectLabel:
          type: string
        request:
          type: string
        trigger:
          type: string
          enum:
            - manual
            - schedule
            - api
            - webhook
            - crm_event
        status:
          type: string
          enum:
            - queued
            - running
            - paused
            - succeeded
            - partial
            - failed
            - cancelled
        counts:
          type: object
          properties:
            total:
              type: integer
            pending:
              type: integer
            succeeded:
              type: integer
            failed:
              type: integer
            skipped:
              type: integer
          required:
            - total
            - pending
            - succeeded
            - failed
            - skipped
        credits:
          type: object
          properties:
            unitPrice:
              type: number
            quoted:
              type: number
            held:
              type: number
            charged:
              type: number
          required:
            - unitPrice
            - quoted
            - held
            - charged
        delivery:
          type: object
          properties:
            mode:
              type: string
              enum:
                - digest
                - per_item
            slack:
              type: object
              nullable: true
              properties:
                channel:
                  type: object
                  properties:
                    id:
                      type: string
                      minLength: 1
                    name:
                      type: string
                      minLength: 1
                  required:
                    - id
                    - name
              required:
                - channel
            webhook:
              type: object
              nullable: true
              properties:
                url:
                  type: string
              required:
                - url
            callbackUrl:
              type: string
              nullable: true
          required:
            - mode
            - slack
            - webhook
            - callbackUrl
        idempotencyKey:
          type: string
          nullable: true
        createdBy:
          type: object
          nullable: true
          properties:
            oId:
              type: string
            email:
              type: string
          required:
            - oId
            - email
        summary:
          type: object
          nullable: true
          properties:
            line:
              type: string
            deliveries:
              type: array
              items:
                type: object
                properties:
                  destination:
                    type: string
                  ok:
                    type: boolean
                  message:
                    type: string
                required:
                  - destination
                  - ok
                  - message
            stoppedReason:
              type: string
              nullable: true
          required:
            - line
            - deliveries
            - stoppedReason
        error:
          type: string
          nullable: true
        pauseReason:
          type: string
          nullable: true
          enum:
            - user
            - deployment
            - null
        createdAt:
          type: string
        startedAt:
          type: string
          nullable: true
        finishedAt:
          type: string
          nullable: true
      required:
        - oId
        - subject
        - subjectLabel
        - request
        - trigger
        - status
        - counts
        - credits
        - delivery
        - idempotencyKey
        - createdBy
        - summary
        - error
        - pauseReason
        - createdAt
        - startedAt
        - finishedAt
    RunItem:
      type: object
      properties:
        oId:
          type: string
        index:
          type: integer
        label:
          type: string
        status:
          type: string
          enum:
            - queued
            - running
            - waiting
            - paused
            - succeeded
            - failed
            - skipped
        item:
          type: string
        output:
          oneOf:
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - skill
                skillRunOId:
                  type: string
                title:
                  type: string
                  nullable: true
                assetUrl:
                  type: string
                  nullable: true
              required:
                - kind
                - skillRunOId
                - title
                - assetUrl
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - prioritized_abm
                resultOId:
                  type: string
                displayScore:
                  type: integer
                  nullable: true
              required:
                - kind
                - resultOId
                - displayScore
            - type: object
              properties:
                kind:
                  type: string
                  enum:
                    - deal_deliverable
                buildOId:
                  type: string
                assetUrl:
                  type: string
                  nullable: true
              required:
                - kind
                - buildOId
                - assetUrl
            - nullable: true
        creditsCharged:
          type: number
        error:
          type: string
          nullable: true
        pauseReason:
          type: string
          nullable: true
          enum:
            - user
            - deployment
            - null
        startedAt:
          type: string
          nullable: true
        finishedAt:
          type: string
          nullable: true
      required:
        - oId
        - index
        - label
        - status
        - item
        - output
        - creditsCharged
        - error
        - pauseReason
        - startedAt
        - finishedAt
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api_key

````

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