LangWatch Coding Agent API

openapi: 3.2.0
info:
  title: LangWatch Coding Agent API
  description: LangWatch openapi spec
  version: 1.0.0
servers:
- url: https://app.langwatch.ai
security:
- project_api_key: []
tags:
- name: Coding Agent
paths:
  /api/v1/coding-agent/sessions/{sessionId}/events:
    get:
      operationId: getApiCodingAgentSessionsBySessionIdEvents
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      type: object
                      properties:
                        sessionId:
                          type: string
                        timeUnixMs:
                          type: number
                        recordId:
                          type: string
                        eventKind:
                          type: string
                        agent:
                          type: string
                        sessionKeySource:
                          type: string
                        traceId:
                          type: string
                        spanId:
                          type: string
                        promptId:
                          type: string
                        querySource:
                          type: string
                        agentType:
                          type: string
                        eventSequence:
                          type: number
                        requestId:
                          type: string
                        model:
                          type: string
                        inputTokens:
                          type: number
                        outputTokens:
                          type: number
                        cacheReadTokens:
                          type: number
                        cacheCreationTokens:
                          type: number
                        costUsd:
                          type: number
                        durationMs:
                          type: number
                        ttftMs:
                          type: number
                        attempt:
                          type: number
                        speed:
                          type: string
                        stopReason:
                          type: string
                        preTokens:
                          type: number
                        postTokens:
                          type: number
                        compactionTrigger:
                          type: string
                        precomputeReuse:
                          type: string
                        statusCode:
                          type: string
                        errorType:
                          type: string
                        rateLimitCarrier:
                          type: string
                        retryDurationMs:
                          type: number
                        toolName:
                          type: string
                        success:
                          type: string
                        decision:
                          type: string
                        decisionSource:
                          type: string
                        toolInputBytes:
                          type: number
                        toolResultBytes:
                          type: number
                        promptChars:
                          type: number
                        totalTokens:
                          type: number
                        repositoryHost:
                          type: string
                        repositoryOwner:
                          type: string
                        repositoryName:
                          type: string
                        branch:
                          type: string
                      required:
                      - sessionId
                      - timeUnixMs
                      - recordId
                      - eventKind
                      - agent
                      - sessionKeySource
                      - traceId
                      - spanId
                      - promptId
                      - querySource
                      - agentType
                      - eventSequence
                      - requestId
                      - model
                      - inputTokens
                      - outputTokens
                      - cacheReadTokens
                      - cacheCreationTokens
                      - costUsd
                      - durationMs
                      - ttftMs
                      - attempt
                      - speed
                      - stopReason
                      - preTokens
                      - postTokens
                      - compactionTrigger
                      - precomputeReuse
                      - statusCode
                      - errorType
                      - rateLimitCarrier
                      - retryDurationMs
                      - toolName
                      - success
                      - decision
                      - decisionSource
                      - toolInputBytes
                      - toolResultBytes
                      - promptChars
                      - totalTokens
                      - repositoryHost
                      - repositoryOwner
                      - repositoryName
                      - branch
                      additionalProperties: false
                  nextCursor:
                    type:
                    - string
                    - 'null'
                required:
                - events
                - nextCursor
                additionalProperties: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
      description: List a coding-agent session's events (model calls, compactions, rate limits, tool runs, prompts) in time order, keyset-paginated. Pass the previous response's nextCursor to continue; filter with kinds (comma-separated).
      summary: List coding agent session events
      security:
      - project_api_key: []
      x-access-policy:
        kind: handlerManaged
        credential:
        - project_api_key
        permissions:
        - traces:view
      parameters:
      - in: path
        name: sessionId
        schema:
          type: string
          minLength: 1
        required: true
        description: The agent's own session id (session.id / conversation id).
      - in: query
        name: limit
        schema:
          default: 500
          type: integer
          exclusiveMinimum: 0
          maximum: 1000
      - in: query
        name: kinds
        schema:
          type: string
        description: 'Comma-separated event kinds to include. Known kinds: model_call, compaction, rate_limit, api_error, retries_exhausted, tool_result, tool_decision, user_prompt, subagent_completed.'
      - in: query
        name: from
        schema:
          type: number
        description: Epoch ms lower bound on event time; with `to`, prunes storage partitions for faster reads.
      - in: query
        name: to
        schema:
          type: number
        description: Epoch ms upper bound on event time.
      - in: query
        name: cursor
        schema:
          type: string
        description: Opaque keyset cursor from the previous response's nextCursor.
      tags:
      - Coding Agent
  /api/coding-agent/pull-request-usage:
    get:
      operationId: getApiCodingAgentPullRequestUsage
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  pullRequest:
                    type: object
                    properties:
                      repositoryHost:
                        type: string
                      repositoryFullName:
                        type: string
                      prNumber:
                        type: number
                      headBranch:
                        type: string
                      htmlUrl:
                        type: string
                      state:
                        type: string
                      isDraft:
                        type: boolean
                      authorLogin:
                        type:
                        - string
                        - 'null'
                      prCreatedAtMs:
                        type: number
                      prClosedAtMs:
                        type:
                        - number
                        - 'null'
                      prMergedAtMs:
                        type:
                        - number
                        - 'null'
                    required:
                    - repositoryHost
                    - repositoryFullName
                    - prNumber
                    - headBranch
                    - htmlUrl
                    - state
                    - isDraft
                    - authorLogin
                    - prCreatedAtMs
                    - prClosedAtMs
                    - prMergedAtMs
                    additionalProperties: false
                  rows:
                    type: array
                    items:
                      type: object
                      properties:
                        projectId:
                          type: string
                        projectSlug:
                          type: string
                        contributorLabel:
                          type: string
                        contributorIsProject:
                          type: boolean
                        agent:
                          type: string
                        models:
                          type: array
                          items:
                            type: string
                        sessionsCount:
                          type: number
                        inputTokens:
                          type: number
                        outputTokens:
                          type: number
                        cacheReadTokens:
                          type: number
                        cacheCreationTokens:
                          type: number
                        totalTokens:
                          type: number
                        costUsd:
                          type:
                          - number
                          - 'null'
                        billedCostUsd:
                          type:
                          - number
                          - 'null'
                        nonBilledCostUsd:
                          type:
                          - number
                          - 'null'
                      required:
                      - projectId
                      - projectSlug
                      - contributorLabel
                      - contributorIsProject
                      - agent
                      - models
                      - sessionsCount
                      - inputTokens
                      - outputTokens
                      - cacheReadTokens
                      - cacheCreationTokens
                      - totalTokens
                      - costUsd
                      - billedCostUsd
                      - nonBilledCostUsd
                      additionalProperties: false
                  totals:
                    type: object
                    properties:
                      sessionsCount:
                        type: number
                      inputTokens:
                        type: number
                      outputTokens:
                        type: number
                      cacheReadTokens:
                        type: number
                      cacheCreationTokens:
                        type: number
                      totalTokens:
                        type: number
                      costUsd:
                        type:
                        - number
                        - 'null'
                      billedCostUsd:
                        type:
                        - number
                        - 'null'
                      nonBilledCostUsd:
                        type:
                        - number
                        - 'null'
                    required:
                    - sessionsCount
                    - inputTokens
                    - outputTokens
                    - cacheReadTokens
                    - cacheCreationTokens
                    - totalTokens
                    - costUsd
                    - billedCostUsd
                    - nonBilledCostUsd
                    additionalProperties: false
                  modelBreakdown:
                    type: array
                    items:
                      type: object
                      properties:
                        model:
                          type: string
                        inputTokens:
                          type: number
                        outputTokens:
                          type: number
                        cacheReadTokens:
                          type: number
                        cacheCreationTokens:
                          type: number
                        totalTokens:
                          type: number
                        costUsd:
                          type:
                          - number
                          - 'null'
                        tokensKnown:
                          type: boolean
                      required:
                      - model
                      - inputTokens
                      - outputTokens
                      - cacheReadTokens
                      - cacheCreationTokens
                      - totalTokens
                      - costUsd
                      - tokensKnown
                      additionalProperties: false
                required:
                - pullRequest
                - rows
                - totals
                - modelBreakdown
                additionalProperties: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
      description: 'Assistant usage for one pull request: sessions, tokens and cost, grouped by contributor and agent, plus per-model totals, over the pull request''s whole lifetime rather than a time window. Every row and the totals split cost three ways: the part priced per token, the part a bundled subscription already covers, and the list-price total of both. Per-model totals carry the list price only. Cost is calculated from the tokens the agent reported and LangWatch''s model prices, so it estimates spend rather than restating a provider invoice. Requires a personal-project API key; rows appear only for projects the calling user may view, and cost only for those they may price.'
      summary: Get pull request coding agent usage
      security:
      - project_api_key: []
      x-access-policy:
        kind: handlerManaged
        credential:
        - project_api_key
        permissions:
        - traces:view
      parameters:
      - in: query
        name: repository
        schema:
          type: string
          pattern: ^[^/\s]+\/[^/\s]+$
        required: true
        description: The repository as "owner/name". Case is folded by the mapping store.
      - in: query
        name: pullRequest
        schema:
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
        required: true
        description: The pull request number.
      - in: query
        name: host
        schema:
          type: string
          minLength: 1
        description: The repository's host, e.g. github.com.
      tags:
      - Coding Agent
  /api/v1/coding-agent/pull-request-usage:
    get:
      operationId: getPullRequestUsage
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  pullRequest:
                    type: object
                    properties:
                      repositoryHost:
                        type: string
                      repositoryFullName:
                        type: string
                      prNumber:
                        type: number
                      headBranch:
                        type: string
                      htmlUrl:
                        type: string
                      state:
                        type: string
                      isDraft:
                        type: boolean
                      authorLogin:
                        type:
                        - string
                        - 'null'
                      prCreatedAtMs:
                        type: number
                      prClosedAtMs:
                        type:
                        - number
                        - 'null'
                      prMergedAtMs:
                        type:
                        - number
                        - 'null'
                    required:
                    - repositoryHost
                    - repositoryFullName
                    - prNumber
                    - headBranch
                    - htmlUrl
                    - state
                    - isDraft
                    - authorLogin
                    - prCreatedAtMs
                    - prClosedAtMs
                    - prMergedAtMs
                    additionalProperties: false
                  rows:
                    type: array
                    items:
                      type: object
                      properties:
                        projectId:
                          type: string
                        projectSlug:
                          type: string
                        contributorLabel:
                          type: string
                        contributorIsProject:
                          type: boolean
                        agent:
                          type: string
                        models:
                          type: array
                          items:
                            type: string
                        sessionsCount:
                          type: number
                        inputTokens:
                          type: number
                        outputTokens:
                          type: number
                        cacheReadTokens:
                          type: number
                        cacheCreationTokens:
                          type: number
                        totalTokens:
                          type: number
                        costUsd:
                          type:
                          - number
                          - 'null'
                        billedCostUsd:
                          type:
                          - number
                          - 'null'
                        nonBilledCostUsd:
                          type:
                          - number
                          - 'null'
                      required:
                      - projectId
                      - projectSlug
                      - contributorLabel
                      - contributorIsProject
                      - agent
                      - models
                      - sessionsCount
                      - inputTokens
                      - outputTokens
                      - cacheReadTokens
                      - cacheCreationTokens
                      - totalTokens
                      - costUsd
                      - billedCostUsd
                      - nonBilledCostUsd
                      additionalProperties: false
                  totals:
                    type: object
                    properties:
                      sessionsCount:
                        type: number
                      inputTokens:
                        type: number
                      outputTokens:
                        type: number
                      cacheReadTokens:
                        type: number
                      cacheCreationTokens:
                        type: number
                      totalTokens:
                        type: number
                      costUsd:
                        type:
                        - number
                        - 'null'
                      billedCostUsd:
                        type:
                        - number
                        - 'null'
                      nonBilledCostUsd:
                        type:
                        - number
                        - 'null'
                    required:
                    - sessionsCount
                    - inputTokens
                    - outputTokens
                    - cacheReadTokens
                    - cacheCreationTokens
                    - totalTokens
                    - costUsd
                    - billedCostUsd
                    - nonBilledCostUsd
                    additionalProperties: false
                  modelBreakdown:
                    type: array
                    items:
                      type: object
                      properties:
                        model:
                          type: string
                        inputTokens:
                          type: number
                        outputTokens:
                          type: number
                        cacheReadTokens:
                          type: number
                        cacheCreationTokens:
                          type: number
                        totalTokens:
                          type: number
                        costUsd:
                          type:
                          - number
                          - 'null'
                        tokensKnown:
                          type: boolean
                      required:
                      - model
                      - inputTokens
                      - outputTokens
                      - cacheReadTokens
                      - cacheCreationTokens
                      - totalTokens
                      - costUsd
                      - tokensKnown
                      additionalProperties: false
                required:
                - pullRequest
                - rows
                - totals
                - modelBreakdown
                additionalProperties: false
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
      description: 'Assistant usage for one pull request: sessions, tokens and cost, grouped by contributor and agent, plus per-model totals, over the pull request''s whole lifetime rather than a time window. Every row and the totals split cost three ways: the part priced per token, the part a bundled subscription already covers, and the list-price total of both. Per-model totals carry the list price only. Cost is calculated from the tokens the agent reported and LangWatch''s model prices, so it estimates spend rather than restating a provider invoice. Authenticate with an organization API key and nothing else: no project id is sent anywhere. A key created for you reads with your own access; an organization service key, such as one a continuous integration job holds, reads with the access its bindings grant. Rows appear only for projects the key may view, and cost only for those it may price.'
      summary: Get pull request coding agent usage
      security:
      - admin_api_key: []
      x-access-policy:
        kind: handlerManaged
        credential:
        - organization_api_key
        permissions: []
      parameters:
      - in: query
        name: repository
        schema:
          type: string
          pattern: ^[^/\s]+\/[^/\s]+$
        required: true
        description: The repository as "owner/name". Case is folded by the mapping store.
      - in: query
        name: pullRequest
        schema:
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
        required: true
        description: The pull request number.
      - in: query
        name: host
        schema:
          type: string
          minLength: 1
        description: The repository's host, e.g. github.com.
      tags:
      - Coding Agent
components:
  securitySchemes:
    project_api_key:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: 'Project API key for sending traces and accessing project-scoped resources. Format: sk-lw-... (no underscore). Obtain one by creating a project via the Admin API or the LangWatch UI.'
    admin_api_key:
      type: http
      scheme: bearer
      description: 'Admin API key for organization-level operations (managing projects, API keys). Create one in Settings > API Keys or via POST /api/api-keys. Format: sk-lw-{id}_{secret}.'
    scim_bearer:
      type: http
      scheme: bearer
      description: SCIM token for one organization's directory connection, created with POST /api/scim-tokens or in Settings > SCIM. It authenticates provisioning calls only, and stops working if the organization's Enterprise plan lapses.
    cli_access_token:
      type: http
      scheme: bearer
      description: The device session the LangWatch CLI holds after `langwatch login`. It acts as the person who signed in, in the organization they chose, and expires unless the CLI refreshes it.
    instance_admin_key:
      type: http
      scheme: bearer
      description: Instance administrator key, set as LANGWATCH_INSTANCE_ADMIN_API_KEY on a self-hosted deployment. It exists to create the first organization, before any organization key does; every other management API takes an organization key instead.
    internal_secret:
      type: http
      scheme: bearer
      description: The deployment's own shared secret, presented by another LangWatch service rather than by a customer. The families behind it are ingress-blocked; they are described so a self-hosted operator can see what the deployment talks to itself about.
x-provenance:
  method: harvested
  publisher: LangWatch
  source: https://app.langwatch.ai/api/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)