openapi: 3.0.1
info:
  title: dbt Cloud Administrative Accounts Runs API
  description: The dbt Cloud Administrative API enables programmatic administration of a dbt Cloud account. Use it to list and trigger jobs, poll and cancel runs, download run artifacts, and manage accounts, projects, and environments. This document models the documented v2 REST surface served from https://cloud.getdbt.com/api/v2. Requests are authenticated with a Bearer service token or personal access token. dbt Labs also offers a v3 REST API for additional resource management, a GraphQL Discovery (Metadata) API at metadata.cloud.getdbt.com/graphql, and a Semantic Layer API (GraphQL and JDBC).
  termsOfService: https://www.getdbt.com/cloud/terms
  contact:
    name: dbt Labs Support
    url: https://docs.getdbt.com/docs/dbt-cloud-apis/overview
  version: '2'
servers:
- url: https://cloud.getdbt.com/api/v2
  description: dbt Cloud Administrative API v2 (multi-tenant North America). Account-specific regions use cloud.getdbt.com, emea.dbt.com, au.dbt.com, or a single-tenant host.
security:
- BearerAuthentication: []
tags:
- name: Runs
  description: Job run history, status, and lifecycle.
paths:
  /accounts/{account_id}/runs/:
    get:
      operationId: listRuns
      tags:
      - Runs
      summary: List runs in an account, with optional filtering and ordering.
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: job_definition_id
        in: query
        schema:
          type: integer
        description: Filter runs by job ID.
      - name: order_by
        in: query
        schema:
          type: string
        description: Field to order results by (e.g. -id for most recent first).
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunListResponse'
  /accounts/{account_id}/runs/{id}/:
    get:
      operationId: retrieveRun
      tags:
      - Runs
      summary: Retrieve a run by ID.
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - $ref: '#/components/parameters/PathId'
      - name: include_related
        in: query
        schema:
          type: string
        description: Comma-separated related fields to include (e.g. trigger,job,run_steps).
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunResponse'
  /accounts/{account_id}/runs/{run_id}/cancel/:
    post:
      operationId: cancelRun
      tags:
      - Runs
      summary: Cancel a run that is queued or in progress.
      parameters:
      - $ref: '#/components/parameters/AccountId'
      - name: run_id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunResponse'
components:
  schemas:
    RunResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/StatusMeta'
        data:
          $ref: '#/components/schemas/Run'
    RunListResponse:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/StatusMeta'
        data:
          type: array
          items:
            $ref: '#/components/schemas/Run'
        extra:
          type: object
          properties:
            pagination:
              $ref: '#/components/schemas/Pagination'
    Run:
      type: object
      properties:
        id:
          type: integer
        account_id:
          type: integer
        project_id:
          type: integer
        job_definition_id:
          type: integer
        environment_id:
          type: integer
        status:
          type: integer
          description: 1=Queued, 2=Starting, 3=Running, 10=Success, 20=Error, 30=Cancelled.
        status_humanized:
          type: string
        git_branch:
          type: string
        git_sha:
          type: string
        is_complete:
          type: boolean
        is_success:
          type: boolean
        is_error:
          type: boolean
        is_cancelled:
          type: boolean
        href:
          type: string
        created_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
    Pagination:
      type: object
      properties:
        count:
          type: integer
        total_count:
          type: integer
    StatusMeta:
      type: object
      properties:
        code:
          type: integer
        is_success:
          type: boolean
        user_message:
          type: string
        developer_message:
          type: string
  parameters:
    AccountId:
      name: account_id
      in: path
      required: true
      schema:
        type: integer
      description: Numeric dbt Cloud account ID.
    PathId:
      name: id
      in: path
      required: true
      schema:
        type: integer
      description: Numeric resource ID.
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        maximum: 100
      description: Maximum number of results to return (max 100).
    Offset:
      name: offset
      in: query
      schema:
        type: integer
      description: Number of results to skip for pagination.
  securitySchemes:
    BearerAuthentication:
      type: http
      scheme: bearer
      description: 'dbt Cloud service token or personal access token passed in the Authorization header as ''Authorization: Token <token>'' or ''Authorization: Bearer <token>''.'