Usage and billing

Usage is counted per organization and per calendar month (UTC), and compared with the monthly quotas of the organization's plan. This page lists what each endpoint counts, what is free, how to read the counters, and the limits of each plan.

What is metered

The meter keeps four counters per organization and month:

What each endpoint adds:

What is free

• Cached research answers. Asking the same research question with the same options again within 10 minutes returns the stored answer with "cached": true, and it is not metered. The cache is kept by each API server, so on a deployment with several servers a repeat can still run (and be metered) again. Pass "no_cache": true to force a new, metered run.
• Map. Map is not metered, but it is refused with 402 once the page quota is used up.
• Reads and polling. Crawl status, cancellation, crawl errors and GET /whoami are never metered.
• Rejected and failed requests. A request refused before any work starts (validation, scope, rate limit or quota) costs nothing, and so do a scrape whose page could not be fetched, a search the engines did not answer, and a research run that failed or timed out.

Reading usage

The dashboard shows the current period under Billing (Billing & usage). The same numbers come from the API:

This endpoint takes a session token from a member of the organization; API keys cannot read usage. GET /whoami with an API key returns the organization's plan.

curl "https://xdive.dev/api/orgs/$ORG_ID/usage" \
  -H "Authorization: Bearer $SESSION_TOKEN"

{
  "browserSecondsUsed": 45,
  "crawlsUsed": 4,
  "limits": {
    "name": "free",
    "monthlyPages": 1000,
    "monthlySearches": 100,
    "monthlyBrowserSeconds": 600,
    "maxBrowserSessions": 1,
    "maxSchedules": 3,
    "requestsPerMinute": 60,
    "maxConcurrentRequests": 5,
    "maxConcurrentCrawls": 2
  },
  "pagesUsed": 312,
  "period": "2026-10",
  "plan": "free",
  "proxy": {
    "enabled": false,
    "monthlyPages": 200,
    "pagesUsed": 0
  },
  "schedules": 1,
  "searchesUsed": 27
}

Counters are updated within seconds of the work, not instantly.

Per-key budgets

An API key can have its own monthly page and search budget, on top of the plan quota. Give a key with a budget to an AI agent or a contractor, and it stops at that budget without using up the organization's quota.

curl -X POST "$XDIVE_URL/api/orgs/$ORG_ID/api-keys" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "research agent", "scopes": ["scrape", "search"], "monthly_page_limit": 500, "monthly_search_limit": 100}'

• 0, the default, means only the plan quota applies.
• Change a budget with PATCH /orgs/{id}/api-keys/{keyId} and {"monthly_page_limit": 1000}. An omitted field keeps its value. The change applies at once.
• GET /orgs/{id}/api-keys lists each key's pagesUsed and searchesUsed this month.
• A request over the key's budget gets 402 QUOTA_EXCEEDED, and the message names the key's budget. A crawl started with less budget left than its max_pages is shortened to what is left. A batch scrape with more URLs than the budget allows is refused.
• Budgets reset with the plan period, at the start of each calendar month (UTC).

Plans

Every organization is on one plan. New organizations start on free.

When a monthly quota is used up, the requests that need it return 402 until the next month or an upgrade. See Errors and limits for the details and for how the per-minute and concurrency limits behave.

Changing plans

Only the organization's owner can change its plan, from Billing in the dashboard.

• When the server has billing configured, upgrading goes through a hosted checkout (POST /orgs/{id}/billing/checkout with {"plan": "pro"} returns its url), and the new plan applies once the payment is confirmed. Downgrading to free is immediate.
• When billing is not configured, as on many self-hosted servers, the owner switches plans directly with PUT /orgs/{id}/plan and {"plan": "pro"}.