Happyrobot Runs API

openapi: 3.2.0
info:
  title: Happyrobot Runs API
  version: '1.0'
  description: 'Operations tagged Runs across 2 of this provider''s published API definitions: happyrobot-platform-v1-openapi.json, happyrobot-public-api-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://platform.happyrobot.ai/api/v1
- url: https://platform.happyrobot.ai/api/v2
tags:
- name: Runs
paths:
  /use-cases/{use_case_id}/runs:
    get:
      description: 'DEPRECATED: Use the new /runs endpoint instead. Get runs for a use case with pagination.'
      summary: 'DEPRECATED: Get runs'
      deprecated: true
      tags:
      - Runs
      parameters:
      - name: use_case_id
        in: path
        required: true
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        schema:
          type: string
          description: Your API key for authentication. Use Bearer format.
          example: Bearer API_KEY
      - name: x-organization-id
        in: header
        required: true
        schema:
          type: string
          description: The organization ID to use for the request. Required if your user is associated to more than one organization.
      - name: limit
        in: query
        schema:
          type: string
      - name: offset
        in: query
        schema:
          type: string
      - name: sort
        in: query
        description: The sort order of the runs. Defaults to desc.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
          example: desc
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    org_id:
                      type: string
                      format: uuid
                    use_case_id:
                      type: string
                      format: uuid
                    version_id:
                      type: string
                      format: uuid
                    status:
                      type: string
                      enum:
                      - scheduled
                      - running
                      - completed
                      - canceled
                      - failed
                    annotation:
                      type:
                      - string
                      - 'null'
                      enum:
                      - correct
                      - incorrect
                      - critical
                    timestamp:
                      type: string
                      format: date-time
                    data:
                      type: object
                      additionalProperties: {}
                    issuesCount:
                      type: number
                    version:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        slug:
                          type: string
                          maxLength: 256
                        org_id:
                          type: string
                          format: uuid
                        use_case_id:
                          type: string
                          format: uuid
                        version_number:
                          type:
                          - number
                          - 'null'
                        name:
                          type: string
                          maxLength: 256
                        is_published:
                          type: boolean
                        is_live:
                          type: boolean
                        environment:
                          type: string
                          enum:
                          - staging
                          - production
                        source_version_id:
                          type:
                          - string
                          - 'null'
                          format: uuid
                        timestamp:
                          type: string
                          format: date-time
                        published_at:
                          type:
                          - string
                          - 'null'
                          format: date-time
                        is_deleted:
                          type: boolean
                        description:
                          type:
                          - string
                          - 'null'
                        created_by:
                          type:
                          - string
                          - 'null'
                          format: uuid
                      required:
                      - id
                      - slug
                      - org_id
                      - use_case_id
                      - version_number
                      - name
                      - is_published
                      - is_live
                      - environment
                      - source_version_id
                      - timestamp
                      - published_at
                      - is_deleted
                      - description
                      - created_by
                  required:
                  - id
                  - org_id
                  - use_case_id
                  - version_id
                  - status
                  - annotation
                  - timestamp
                  - data
                  - issuesCount
                  - version
        '401':
          description: '401'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                - message
    servers:
    - url: https://platform.happyrobot.ai/api/v1
  /runs:
    get:
      description: Get runs for the organization with the variables you've added to your runs table.
      summary: Get runs
      tags:
      - Runs
      parameters:
      - name: authorization
        in: header
        required: true
        schema:
          type: string
          description: Your API key for authentication. Use Bearer format.
          example: Bearer API_KEY
      - name: x-organization-id
        in: header
        required: true
        schema:
          type: string
          description: The organization ID to use for the request. Required if your user is associated to more than one organization.
      - name: limit
        in: query
        description: The number of runs to return. Defaults to 1000.
        schema:
          type:
          - number
          - 'null'
          maximum: 5000
          example: 1000
      - name: offset
        in: query
        description: The number of runs to skip. Defaults to 0.
        schema:
          type:
          - number
          - 'null'
          example: 500
      - name: use_case_id
        in: query
        description: The ID of the use case to filter runs by. Defaults to all runs in all use cases.
        required: true
        schema:
          type: string
          default: ''
      - name: status
        in: query
        description: The status of the runs to filter by.
        schema:
          type: string
          enum:
          - scheduled
          - running
          - completed
          - canceled
          - failed
          default: success
      - name: start
        in: query
        description: The start date to filter runs by. Defaults to all runs.
        schema:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00.000Z'
      - name: end
        in: query
        description: The end date to filter runs by. Defaults to all runs.
        schema:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00.000Z'
      - name: sort
        in: query
        description: The sort order of the runs by their timestamp (does not sort by completion date). Defaults to desc.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
          example: desc
      - name: completed_start
        in: query
        description: Filter runs by completion date, starting from this date. If not specified, includes runs completed at any time.
        schema:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00.000Z'
      - name: completed_end
        in: query
        description: Filter runs by completion date, ending at this date. If not specified, includes runs completed at any time.
        schema:
          type: string
          format: date-time
          example: '2024-01-01T00:00:00.000Z'
      - name: node_output_filters
        in: query
        description: 'Filters based on a particular node output in the run. The syntax for this property is `''{{node.id}}.property.to.filter.by'': [''{{value}}'']`. The simpliest way to get the key is to add the var to your runs table and to view the keys in the `data` property of the `/runs` response. If you need assistance with this, please reach out to your HappyRobot representative.'
        schema:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    org_id:
                      type: string
                      format: uuid
                    use_case_id:
                      type: string
                      format: uuid
                    version_id:
                      type: string
                      format: uuid
                    status:
                      type: string
                      enum:
                      - scheduled
                      - running
                      - completed
                      - canceled
                      - failed
                    annotation:
                      type:
                      - string
                      - 'null'
                      enum:
                      - correct
                      - incorrect
                      - critical
                    timestamp:
                      type: string
                      format: date-time
                    data:
                      type: object
                      additionalProperties: {}
                      description: 'The values for each column you''ve defined in your runs table. '
                    completed_at:
                      type:
                      - string
                      - 'null'
                      format: date-time
                      description: The timestamp of the last node output for the run.
                  required:
                  - id
                  - org_id
                  - use_case_id
                  - version_id
                  - status
                  - annotation
                  - timestamp
                  - data
                  - completed_at
                description: A list of runs with the data for each column you've added to your runs table.
        '401':
          description: '401'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: The user is not authenticated.
                required:
                - message
    servers:
    - url: https://platform.happyrobot.ai/api/v1
  /runs/{run_id}:
    get:
      description: Get a run by ID with all its events and session outputs.
      summary: Get a run by ID
      tags:
      - Runs
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        schema:
          type: string
          description: Your API key for authentication. Use Bearer format.
          example: Bearer API_KEY
      - name: x-organization-id
        in: header
        required: true
        schema:
          type: string
          description: The organization ID to use for the request. Required if your user is associated to more than one organization.
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  org_id:
                    type: string
                    format: uuid
                  use_case_id:
                    type: string
                    format: uuid
                  version_id:
                    type: string
                    format: uuid
                  status:
                    type: string
                    enum:
                    - scheduled
                    - running
                    - completed
                    - canceled
                    - failed
                  annotation:
                    type:
                    - string
                    - 'null'
                    enum:
                    - correct
                    - incorrect
                    - critical
                  timestamp:
                    type: string
                    format: date-time
                  completed_at:
                    type:
                    - string
                    - 'null'
                    format: date-time
                    description: The timestamp of the last node output for the run.
                  events:
                    type: array
                    items:
                      discriminator:
                        propertyName: type
                      oneOf:
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                            - action
                          timestamp:
                            type: string
                            format: date-time
                          integration_name:
                            type: string
                          event_name:
                            type: string
                          intermediate:
                            type: object
                            properties:
                              id:
                                type: string
                                format: uuid
                              run_id:
                                type:
                                - string
                                - 'null'
                                format: uuid
                              node_id:
                                type: string
                                format: uuid
                              event_id:
                                type:
                                - string
                                - 'null'
                                format: uuid
                              session_id:
                                type:
                                - string
                                - 'null'
                                format: uuid
                              name:
                                type:
                                - string
                                - 'null'
                                maxLength: 256
                              data:
                                type:
                                - object
                                - 'null'
                                additionalProperties: {}
                              error:
                                type:
                                - string
                                - 'null'
                              timestamp:
                                type: string
                                format: date-time
                              data_deleted:
                                type: boolean
                            required:
                            - id
                            - run_id
                            - node_id
                            - event_id
                            - session_id
                            - name
                            - data
                            - error
                            - timestamp
                            - data_deleted
                          output:
                            type:
                            - object
                            - 'null'
                            additionalProperties: {}
                          node_id:
                            type: string
                        required:
                        - type
                        - timestamp
                        - output
                        - node_id
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                            - session
                          id:
                            type: string
                          duration:
                            type:
                            - number
                            - 'null'
                          actions:
                            type: array
                            items:
                              type: object
                              additionalProperties: {}
                          messages:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                session_id:
                                  type:
                                  - string
                                  - 'null'
                                  format: uuid
                                chat_session_id:
                                  type:
                                  - string
                                  - 'null'
                                  format: uuid
                                role:
                                  type: string
                                  enum:
                                  - assistant
                                  - user
                                  - tool
                                  - event
                                content:
                                  type: string
                                tool_calls:
                                  type:
                                  - array
                                  - 'null'
                                  items:
                                    type: object
                                    properties:
                                      function:
                                        type: object
                                        properties:
                                          name:
                                            type: string
                                          arguments:
                                            type: string
                                        required:
                                        - name
                                        - arguments
                                    required:
                                    - function
                                name:
                                  type:
                                  - string
                                  - 'null'
                                  maxLength: 256
                                is_filler:
                                  type: boolean
                                is_interrupted:
                                  type: boolean
                                is_natural_cut:
                                  type: boolean
                                latency_breakdown:
                                  type:
                                  - object
                                  - 'null'
                                  properties:
                                    network:
                                      type: number
                                    initial_wait:
                                      type: number
                                    transcriber:
                                      type: number
                                    eos:
                                      type: number
                                    eos_wait:
                                      type: number
                                    llm:
                                      type: number
                                    tts:
                                      type: number
                                  required:
                                  - network
                                  - initial_wait
                                  - transcriber
                                  - eos
                                  - eos_wait
                                  - llm
                                  - tts
                                timestamp:
                                  type: string
                                  format: date-time
                                data_deleted:
                                  type: boolean
                              required:
                              - id
                              - session_id
                              - chat_session_id
                              - role
                              - content
                              - tool_calls
                              - name
                              - is_filler
                              - is_interrupted
                              - is_natural_cut
                              - latency_breakdown
                              - timestamp
                              - data_deleted
                          timestamp:
                            type: string
                            format: date-time
                          sip_code:
                            type:
                            - string
                            - 'null'
                            description: The SIP error code for the run, if any.
                          sip_reason:
                            type:
                            - string
                            - 'null'
                            description: The SIP error reason for the run, if any.
                        required:
                        - type
                        - id
                        - duration
                        - actions
                        - messages
                        - timestamp
                        - sip_code
                        - sip_reason
                    description: The events for the run.
                  issues:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        use_case_id:
                          type: string
                          format: uuid
                        org_id:
                          type: string
                          format: uuid
                        run_id:
                          type: string
                          format: uuid
                        run_version_id:
                          type: string
                          format: uuid
                        status:
                          type: string
                          enum:
                          - open
                          - approved
                          - rejected
                          - closed
                        priority:
                          type: string
                          enum:
                          - low
                          - medium
                          - high
                        created_at:
                          type: string
                          format: date-time
                        type:
                          type: string
                          enum:
                          - transcriber
                          - message
                          - tool_call
                          - end_of_sentence
                          - run
                          - interruption
                        updated_at:
                          type: string
                          format: date-time
                        assignee:
                          type:
                          - string
                          - 'null'
                          format: uuid
                        created_by:
                          type: string
                          format: uuid
                        updated_by:
                          type: string
                          format: uuid
                        message_id:
                          type:
                          - string
                          - 'null'
                          format: uuid
                        correction:
                          type:
                          - string
                          - 'null'
                        correction_reason:
                          type:
                          - string
                          - 'null'
                        northstar_id:
                          type:
                          - string
                          - 'null'
                          format: uuid
                      required:
                      - id
                      - use_case_id
                      - org_id
                      - run_id
                      - run_version_id
                      - status
                      - priority
                      - created_at
                      - type
                      - updated_at
                      - assignee
                      - created_by
                      - updated_by
                      - message_id
                      - correction
                      - correction_reason
                      - northstar_id
                    description: The issues for the run.
                  version:
                    type:
                    - object
                    - 'null'
                    properties:
                      id:
                        type: string
                        format: uuid
                      slug:
                        type: string
                        maxLength: 256
                      org_id:
                        type: string
                        format: uuid
                      use_case_id:
                        type: string
                        format: uuid
                      version_number:
                        type:
                        - number
                        - 'null'
                      name:
                        type: string
                        maxLength: 256
                      is_published:
                        type: boolean
                      is_live:
                        type: boolean
                      environment:
                        type: string
                        enum:
                        - staging
                        - production
                      source_version_id:
                        type:
                        - string
                        - 'null'
                        format: uuid
                      timestamp:
                        type: string
                        format: date-time
                      published_at:
                        type:
                        - string
                        - 'null'
                        format: date-time
                      is_deleted:
                        type: boolean
                      description:
                        type:
                        - string
                        - 'null'
                      created_by:
                        type:
                        - string
                        - 'null'
                        format: uuid
                    required:
                    - id
                    - slug
                    - org_id
                    - use_case_id
                    - version_number
                    - name
                    - is_published
                    - is_live
                    - environment
                    - source_version_id
                    - timestamp
                    - published_at
                    - is_deleted
                    - description
                    - created_by
                    description: The version for the run.
                required:
                - id
                - org_id
                - use_case_id
                - version_id
                - status
                - annotation
                - timestamp
                - completed_at
                - events
                - issues
                - version
                description: A run with all its events.
        '401':
          description: '401'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: The user is not authenticated.
                required:
                - message
        '404':
          description: '404'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: The run was not found.
                required:
                - message
    servers:
    - url: https://platform.happyrobot.ai/api/v1
  /runs/{run_id}/recordings:
    get:
      description: Get a run's recordings.
      summary: Get a run's recordings
      tags:
      - Runs
      parameters:
      - name: run_id
        in: path
        required: true
        schema:
          type: string
      - name: authorization
        in: header
        required: true
        schema:
          type: string
          description: Your API key for authentication. Use Bearer format.
          example: Bearer API_KEY
      - name: x-organization-id
        in: header
        required: true
        schema:
          type: string
          description: The organization ID to use for the request. Required if your user is associated to more than one organization.
      - name: session_id
        in: query
        description: The session ID to filter recordings by.
        schema:
          type: string
      - name: url_expires_in_days
        in: query
        description: The number of days to expire the presigned URL for.
        schema:
          type:
          - number
          - 'null'
          default: 1
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  recordings:
                    type: array
                    items:
                      type: object
                      properties:
                        session_id:
                          type: string
                          description: The ID of the session for this recording.
                        url:
                          type: string
                          description: The presigned

# --- truncated at 32 KB (82 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/happyrobot/refs/heads/main/openapi/happyrobot-runs-api-openapi.yml