---
title: "Get organization usage across all API keys"
method: POST
path: "/org-usage"
---

# Get organization usage across all API keys

`POST /org-usage`

## Request

- Base URL: `https://api.tavily.com`
- URL: `https://api.tavily.com/org-usage`
- Auth: HTTP bearer

Retrieve usage (credits), pay-as-you-go USD cost, and request counts for **every API key under an organization you own**, mirroring the platform's Usage analytics page.

Identify the organization by **name** in the request body. Authenticate with the organization owner's **personal API key** — the key from the owner's own personal account, **not** an organization or enterprise API key. Supports date-range, project, and depth filtering.

## Request body

- object
  - `organization_name` string, required: Exact organization name (case-sensitive). You must be the owner of this organization.
  - `start_date` string, date: Inclusive start of the usage window (YYYY-MM-DD). Defaults to the start of the current billing cycle.
  - `end_date` string, date: Inclusive end of the usage window (YYYY-MM-DD). Defaults to today.
  - `project_id` string: Scope usage to a single project.
  - `depth` 'basic' | 'advanced' | 'fast' | 'pro' | 'mini' | 'auto' | 'ultra-fast': Scope usage to a single request depth.

## Response `200`

Organization usage returned successfully

- object
  - `organization` object
    - `name` string
    - `filters` object: Echo of the filters applied to this response
      - `start_date` string
      - `end_date` string
      - `project_id` string
      - `depth` string
  - `totals` object: Aggregated usage across all keys in the organization for the selected window/filters
    - `usage` integer
    - `paygo_cost_usd` number
    - `request_count` integer
    - `by_type` UsageByType: Breakdown per request type
      - `search` UsageMetrics
        - `usage` integer: Credits consumed
        - `paygo_cost_usd` number: Pay-as-you-go cost in USD (overage credits billed at the account's per-credit rate)
        - `request_count` integer: Number of requests
      - `crawl` UsageMetrics
        - `usage` integer: Credits consumed
        - `paygo_cost_usd` number: Pay-as-you-go cost in USD (overage credits billed at the account's per-credit rate)
        - `request_count` integer: Number of requests
      - `extract` UsageMetrics
        - `usage` integer: Credits consumed
        - `paygo_cost_usd` number: Pay-as-you-go cost in USD (overage credits billed at the account's per-credit rate)
        - `request_count` integer: Number of requests
      - `map` UsageMetrics
        - `usage` integer: Credits consumed
        - `paygo_cost_usd` number: Pay-as-you-go cost in USD (overage credits billed at the account's per-credit rate)
        - `request_count` integer: Number of requests
      - `research` UsageMetrics
        - `usage` integer: Credits consumed
        - `paygo_cost_usd` number: Pay-as-you-go cost in USD (overage credits billed at the account's per-credit rate)
        - `request_count` integer: Number of requests
  - `keys` object[]
    - `key` string: API key, masked to the last 5 characters
    - `name` string: Key name
    - `usage` integer
    - `paygo_cost_usd` number
    - `request_count` integer
    - `by_type` UsageByType: Breakdown per request type
      - `search` UsageMetrics
        - `usage` integer: Credits consumed
        - `paygo_cost_usd` number: Pay-as-you-go cost in USD (overage credits billed at the account's per-credit rate)
        - `request_count` integer: Number of requests
      - `crawl` UsageMetrics
        - `usage` integer: Credits consumed
        - `paygo_cost_usd` number: Pay-as-you-go cost in USD (overage credits billed at the account's per-credit rate)
        - `request_count` integer: Number of requests
      - `extract` UsageMetrics
        - `usage` integer: Credits consumed
        - `paygo_cost_usd` number: Pay-as-you-go cost in USD (overage credits billed at the account's per-credit rate)
        - `request_count` integer: Number of requests
      - `map` UsageMetrics
        - `usage` integer: Credits consumed
        - `paygo_cost_usd` number: Pay-as-you-go cost in USD (overage credits billed at the account's per-credit rate)
        - `request_count` integer: Number of requests
      - `research` UsageMetrics
        - `usage` integer: Credits consumed
        - `paygo_cost_usd` number: Pay-as-you-go cost in USD (overage credits billed at the account's per-credit rate)
        - `request_count` integer: Number of requests

## Other responses

- `400`: Invalid start_date; expected format YYYY-MM-DD.
- `401`: Unauthorized: missing or invalid API key.
- `403`: Please authenticate with the organization owner's personal API key, not an organization API key.
- `404`: Organization not found or access denied.
- `422`: organization_name is required.
- `429`: Too many requests - Rate limit exceeded
- `500`: Internal server error
- `504`: Gateway timeout - the usage lookup took too long

## Changes

- **2026-11-03** `c97103b0bfa3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/tavily/apis/tavily-search-and-extract-api/changes/org-usage/post.md)

---

[API](https://skmtc.dev/tavily/apis/tavily-search-and-extract-api.md) - [All operations](https://skmtc.dev/tavily/apis/tavily-search-and-extract-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tavily/apis/tavily-search-and-extract-api/revisions/c97103b0bfa3?raw)