> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.

# Get pull request usage

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.

> Page: https://langwatch.ai/docs/api-reference/coding-agents/get-pull-request-usage
> Source: https://github.com/langwatch/langwatch/blob/main/docs/api-reference/coding-agents/get-pull-request-usage.mdx
> Index of all pages: https://langwatch.ai/docs/llms.txt

## Endpoint

`GET https://app.langwatch.ai/api/v1/coding-agent/pull-request-usage`

## Authentication

### admin_api_key

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}.

```json
{"id":"admin_api_key","type":"http","scheme":"bearer"}
```

## Parameters

### repository (query, required)

The repository as "owner/name". Case is folded by the mapping store.

```json
{"type":"string","pattern":"^[^/\\s]+\\/[^/\\s]+$"}
```

### pullRequest (query, required)

The pull request number.

```json
{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}
```

### host (query, optional)

The repository's host, e.g. github.com.

```json
{"type":"string","minLength":1}
```

## Request example

```bash
curl --request GET \
  --url 'https://app.langwatch.ai/api/v1/coding-agent/pull-request-usage' \
  --header "Authorization: Bearer $LANGWATCH_API_KEY"
```

## Responses

### 200

Success

#### application/json

Schema:

```json
{
  "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"},
          "aiUnits": {"type":["number","null"]}
        },
        "required": [
          "model",
          "inputTokens",
          "outputTokens",
          "cacheReadTokens",
          "cacheCreationTokens",
          "totalTokens",
          "costUsd",
          "tokensKnown",
          "aiUnits"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": ["pullRequest","rows","totals","modelBreakdown"],
  "additionalProperties": false
}
```

### 400

Bad Request

#### application/json

Schema:

```json
{
  "type": "object",
  "properties": {"error":{"type":"string"},"message":{"type":"string"}},
  "required": ["error"]
}
```

### 401

Unauthorized

#### application/json

Schema:

```json
{
  "type": "object",
  "properties": {"error":{"type":"string"},"message":{"type":"string"}},
  "required": ["error"]
}
```

### 422

Unprocessable Entity

#### application/json

Schema:

```json
{
  "type": "object",
  "properties": {"error":{"type":"string"},"message":{"type":"string"}},
  "required": ["error"]
}
```

### 500

Internal Server Error

#### application/json

Schema:

```json
{
  "type": "object",
  "properties": {"error":{"type":"string"},"message":{"type":"string"}},
  "required": ["error"]
}
```
