Ptolemy meters API usage per billing cycle. Each plan includes a monthly quota for API calls and database items. Understanding how usage is counted helps you design efficient integrations and avoid unexpected limits.
What counts as an API call
Every HTTP request made with a robot token counts as one API call against your monthly quota, regardless of the HTTP method or response status code.
Source
Counts?
Notes
Robot token requests
Yes
Every request — GET, POST, PATCH, DELETE — counts as one call.
Webhook deliveries
Yes
The first successful delivery of each event counts as one call. Retries of failed deliveries do not count again.
Human browser sessions
No
Activity in the Ptolemy dashboard does not consume API call quota.
Plan limits
Each workspace has four metered dimensions. Limits depend on your plan tier.
Dimension
What it measures
Limit type
Human seats
Active human members in the workspace. Robot users do not consume seats.
Hard limit
Webhook seats
Registered webhook endpoints. Always a hard limit — no overage available.
Hard limit
Database items
Total count across all eight billable item types: instruments, time series values, composite values, composite value items, markets, market listings, market listing suspensions, and market calendars. Archived items still count.
Soft limit (overage optional)
API calls
Robot token requests + webhook deliveries per billing period.
Soft limit (overage optional)
Workspace admins can check current usage via the dashboard (Workspace Settings → Plan & Usage). Robot integrations can monitor quota via the X-RateLimit-Remaining response header included on every API response.
What happens when you hit a limit
Behaviour depends on the dimension and whether overage billing is enabled.
Overage disabled (default)
API requests return 429 Too Many Requests. Database item creation returns 403 Forbidden. Webhook deliveries that would exceed the API call quota are abandoned.
Overage enabled
Requests continue to succeed. Excess usage is billed at the per-unit overage rate at the end of the billing period.
429 — API call quota exceeded
{
"status": 429,
"error": "too_many_requests",
"message": "API call quota exceeded for this billing period. Enable overage billing or upgrade your plan."
}
Workspace admins receive email notifications when usage crosses 80% and again at 100% of the plan limit. We recommend checking the X-RateLimit-Remaining response header in your integration to detect approaching limits proactively.
Overage billing
On fixed plans (Starter and Growth), overage can be toggled independently across three dimensions.
Toggle
What it controls
allow_api_overage
Robot token API requests that exceed the monthly quota. When off, excess requests return 429. When on, they succeed and are billed at the per-unit rate.
allow_storage_overage
Database item creation that exceeds the plan's item limit. When off, creation returns 403. When on, items are created and billed.
allow_webhook_overage
Webhook deliveries that would push the workspace past its API call quota. When off, deliveries are abandoned. When on, they proceed and count as billable API calls.
When overage is enabled, there is no hard cap — usage will continue to be billed until you disable overage or the billing period ends. Monitor your usage carefully to avoid unexpected charges.
Burst protection
In addition to billing-cycle quotas, Ptolemy applies short-term burst protection to maintain platform stability. Sustained traffic that materially exceeds normal operational patterns may be temporarily throttled. When throttling is applied, the API returns 429 Too Many Requests with a Retry-After header.
429 — Burst throttle response headers
HTTP/1.1 429 Too Many Requests
Retry-After: 5X-RateLimit-Reset: 1713168300
Best practices to avoid throttling:
Use cursor pagination
Fetch pages sequentially rather than making parallel requests for overlapping data.
Respect Retry-After
When you receive a 429, wait the number of seconds in the header before retrying.
Use the filter API
A single POST /instruments/filter is more efficient than many GET requests with different query params.
Subscribe to webhooks
Use push-based webhooks instead of polling for changes. Webhook deliveries are cheaper than repeated list calls.
Usage response headers
Every API response includes headers showing your current billing-period usage:
Header
Description
X-RateLimit-Limit
Your plan's API call quota for the current billing period.
X-RateLimit-Remaining
API calls remaining in the current billing period.
X-RateLimit-Reset
Unix timestamp when the current billing period ends and the quota resets.
Retry-After
Only present on 429 responses. Seconds to wait before retrying.