---
title: "Get usage"
method: GET
path: "/v1/usage"
tags: ["usage"]
---

# Get usage

`GET /v1/usage`

Get organization usage totals, user breakdowns, and the paginated thread activity timeline shown in the usage dashboard. Monetary amounts are decimal US dollar numbers.

## Query parameters

- `orgId` string, required
- `from` string, date-time, required
- `to` string, date-time, required
- `routed` 'paid' | 'no_cost' | 'oss' | 'external_copilot' | 'external_codex' | 'external_byok' | 'external_azure' | 'external_unknown' | 'external_xai' | 'all'
- `userId` string
- `projectIds` string — Comma-separated project IDs to include.
- `agentType` 'build' | 'captain' | 'review' — Filter usage to build, captain, or review activity.
- `sortBy` 'lastActivity' | 'cost' | 'name' | 'diff' | 'owner'
- `sortDirection` 'asc' | 'desc'
- `page` integer
- `pageSize` integer

## Response `200`

Success

- UsageResponse
  - `orgId` string, required
  - `from` string, required
  - `to` string, required
  - `currency` 'USD', required
  - `routed` 'paid' | 'no_cost' | 'oss' | 'external_copilot' | 'external_codex' | 'external_byok' | 'external_azure' | 'external_unknown' | 'external_xai' | 'all', required
  - `totals` object, required
    - `llmDollars` number, required
    - `vmDollars` number, required
    - `totalDollars` number, required
  - `users` object[], required
    - `llmDollars` number, required
    - `vmDollars` number, required
    - `totalDollars` number, required
    - `userId` string, required
    - `userType` 'human' | 'service_user', required
    - `name` string, nullable, required
    - `email` string, nullable, required
    - `imageUrl` string, nullable, required
    - `isServiceUser` boolean, required
  - `items` object[], required
    - `llmDollars` number, required
    - `vmDollars` number, required
    - `totalDollars` number, required
    - `jamId` string, required
    - `jamTitle` string, nullable, required
    - `jamStatus` string, nullable, required
    - `jamAgentType` string, nullable, required
    - `jamProjectId` string, nullable, required
    - `jamCreatedAt` string, nullable, required
    - `jamUpdatedAt` string, nullable, required
    - `userId` string, required
    - `userType` 'human' | 'service_user', required
    - `userName` string, nullable, required
    - `userEmail` string, nullable, required
    - `userImageUrl` string, nullable, required
    - `isServiceUser` boolean, required
    - `taskId` string, nullable, required
    - `taskProjectId` string, nullable, required
    - `taskNumber` integer, nullable, required
    - `taskTitle` string, nullable, required
    - `lastActivityAt` string, required
    - `modelCount` integer, required
    - `diffSummaryByMode` object, nullable, required
      - `uncommitted` object
        - `additions` number, required
        - `deletions` number, required
        - `hasChanges` boolean, required
        - `generatedAt` string, required
        - `baselineRef` string, required
        - `fileCount` number
        - `changedFiles` string[]
      - `pr` object
        - `additions` number, required
        - `deletions` number, required
        - `hasChanges` boolean, required
        - `generatedAt` string, required
        - `baselineRef` string, required
        - `fileCount` number
        - `changedFiles` string[]
      - `run` object
        - `additions` number, required
        - `deletions` number, required
        - `hasChanges` boolean, required
        - `generatedAt` string, required
        - `baselineRef` string, required
        - `fileCount` number
        - `changedFiles` string[]
    - `routedSource` 'paid' | 'no_cost' | 'oss' | 'external_copilot' | 'external_codex' | 'external_byok' | 'external_azure' | 'external_unknown' | 'external_xai', required
    - `routedSpendDollars` object, nullable, required
  - `total` integer, required
  - `page` integer, required
  - `pageSize` integer, required
  - `totalPages` integer, required

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not found
- `422` — Validation error
- `500` — Internal error

---

[API](https://skmtc.dev/capy/apis/capy-api.md) · [All operations](https://skmtc.dev/capy/apis/capy-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/capy/capy-api/revisions/c9ea28cb32b6/schema)