Usage & Rate Limits

These endpoints let you track how much of your plan you’ve used and how much capacity you have right now.

Get Usage

Return request and document counts for the current API key, both for the current calendar month and all-time.

Endpoint

GET /api/v1/usage

Counters in this response have two scopes. Per-key: requests, ingests, queries reflect just what this API key has done. Per-workspace: pages, audio_seconds, and documents_stored reflect the workspace the key belongs to (across all keys and in-app activity).

Response

object

Show Usage object

object

Show Requests counters

integer

Requests made this calendar month

integer

All-time request count

object

Show Ingest counters

integer

Documents ingested this calendar month

integer

All-time ingest count

object

Show Query counters

integer

Queries made this calendar month

integer

All-time query count

object

Show Pages-processed counters

integer

Pages processed this calendar month (workspace-wide)

integer

All-time pages processed (workspace-wide)

object

Show Audio-seconds counters

integer

Seconds of audio processed this calendar month (workspace-wide)

integer

All-time audio seconds processed (workspace-wide)

integer

Number of documents currently in your workspace

Example

curl "https://app.polyvia.ai/api/v1/usage" \
  -H "Authorization: Bearer poly_<your-key>"

from polyvia import Polyvia

client = Polyvia(api_key="poly_...")

usage = client.usage()
print(usage.usage.requests.period)              # requests this month (per key)
print(usage.usage.pages.period)                 # pages this month (workspace)
print(usage.usage.audio_seconds.period / 60)    # minutes of audio this month
print(usage.usage.documents_stored)             # live document count

{
  "usage": {
    "requests":        { "period": 142,  "total": 3801  },
    "ingests":         { "period": 12,   "total": 204   },
    "queries":         { "period": 130,  "total": 3597  },
    "pages":           { "period": 318,  "total": 5421  },
    "audio_seconds":   { "period": 1840, "total": 34920 },
    "documents_stored": 47
  }
}

Get Rate Limits

Return the rate-limit thresholds for your plan and how much capacity remains right now.

Endpoint

GET /api/v1/rate-limits

Response

object

Hard limits for your plan (requests per minute, per month, etc.)

object

Real-time headroom — how much capacity remains in each window.

object

ISO 8601 timestamps of when each counter resets.

Show resets_at fields

string

When the per-minute window resets

string

When the monthly counters reset (first day of next month)

Example

curl "https://app.polyvia.ai/api/v1/rate-limits" \
  -H "Authorization: Bearer poly_<your-key>"

limits = client.rate_limits()
print(limits.limits["requests_per_minute"])
print(limits.current["remaining_this_minute"])
print(limits.resets_at.month)   # ISO timestamp of next monthly reset

{
  "limits": {
    "requests_per_minute": 60,
    "requests_per_month":  10000,
    "documents_per_month": 500,
    "queries_per_month":   2000
  },
  "current": {
    "remaining_this_minute": 58,
    "remaining_requests_this_month":  9858,
    "remaining_documents_this_month": 488,
    "remaining_queries_this_month":   1870
  },
  "resets_at": {
    "minute": "2025-04-23T14:32:00Z",
    "month":  "2025-05-01T00:00:00Z"
  }
}

Rate limits are informational — the API does not block requests when limits are reached, but you should monitor these values and implement back-off logic in production integrations.

Get Started

Products

API Reference

Releases

Usage & Rate Limits

Get Usage

Endpoint

Response

Example

Get Rate Limits

Endpoint

Response

Example

​Get Usage

​Endpoint

​Response

​Example

​Get Rate Limits

​Endpoint

​Response

​Example

Get Usage

Endpoint

Response

Example

Get Rate Limits

Endpoint

Response

Example