Usage
Check your organization’s current API call usage, resource counts, and plan limits.
Get usage
Section titled “Get usage”GET /v1/usageNo query parameters required. Returns usage for the authenticated organization.
Example
Section titled “Example”curl https://api.chronary.ai/v1/usage \ -H "Authorization: Bearer chr_sk_your_key_here"from chronary import Chronary
client = Chronary()
usage = client.usage.get()print(f"Plan: {usage.plan}")print(f"API calls: {usage.api_calls.used}/{usage.api_calls.limit}")print(f"Agents: {usage.agents.used}/{usage.agents.limit}")Response 200 OK
Section titled “Response 200 OK”{ "plan": "free", "period_start": "2026-04-01T00:00:00.000Z", "period_end": "2026-04-30T23:59:59.000Z", "resets_at": "2026-05-01T00:00:00.000Z", "generated_at": "2026-04-25T12:04:07.000Z", "agents": { "used": 1, "limit": 1 }, "calendars": { "used": 1, "limit": 1 }, "events": { "used": 40, "limit": 100 }, "api_calls": { "used": 250, "limit": 1000 }, "webhooks": { "used": 100, "limit": 1000 }, "availability_queries": { "used": 30, "limit": 100 }, "ical_subscriptions": { "used": 0, "limit": 0 }, "proposals": { "used": 0, "limit": 0 }, "recurring_events": { "used": 0, "limit": 1 }, "booking_pages": { "used": 0, "limit": 1 }}Response fields
Section titled “Response fields”Every metric is returned as { used, limit }. A null limit means that metric is unlimited on your plan.
| Field | Description |
|---|---|
plan | Your account’s plan: free, free-agent-unverified (agent signup, not yet verified), developer, pro, or scale (the Custom plan) |
period_start | ISO-8601 start of the current quota period (the calendar month, UTC) |
period_end | ISO-8601 last second of the current quota period (23:59:59 UTC on the month’s last day). Quotas reset on the calendar month, not on your billing date |
resets_at | ISO-8601 first instant of the next UTC month (00:00:00 UTC on the 1st), when the monthly counters reset |
generated_at | ISO-8601 time this response was computed. API calls can lag by up to 30 seconds |
agents | Current agent count vs plan cap |
calendars | Current calendar count vs plan cap |
events | Events created this period vs plan cap |
api_calls | API calls this period vs plan cap |
webhooks | Webhook deliveries this period vs plan cap |
availability_queries | Availability queries this period vs plan cap |
ical_subscriptions | Current iCal subscription count vs plan cap |
proposals | Scheduling proposals created this period vs plan cap |
recurring_events | Current active recurring series count vs plan cap (a concurrent cap, not monthly — deleting a series frees its slot) |
holds | Temporal-hold activity: created, confirmed and expired count this period; active is a live count of unexpired holds right now, not a monthly counter. Not limited on any plan |
Exact plan caps are published via GET /v1/plans and documented in Rate Limits & Quotas.
Usage history
Section titled “Usage history”GET /v1/usage/history?months=6Returns monthly totals for every monthly counter over the last 1 to 12 UTC calendar months, oldest month first. The last entry is the current month, which is still in progress. Requests to this endpoint are not counted toward your API calls. It needs an Organization key or a console session; an Agent key gets 403.
| Query parameter | Description |
|---|---|
months | Number of months to return, 1 to 12. Defaults to 6. Anything else returns 400 validation_error |
Example
Section titled “Example”curl "https://api.chronary.ai/v1/usage/history?months=3" \ -H "Authorization: Bearer chr_sk_your_key_here"import { Chronary } from '@chronary/sdk';
const client = new Chronary();
const history = await client.usage.history({ months: 3 });for (const month of history.data) { console.log(month.period, month.metrics.api_calls, month.is_current ? '(to date)' : '');}from chronary import Chronary
client = Chronary()
history = client.usage.history(months=3)for month in history.data: print(month.period, month.metrics.api_calls)chronary usage history --months 3Response 200 OK
Section titled “Response 200 OK”{ "plan": "free", "months": 2, "limits": { "api_calls": 1000, "events": 100, "webhook_deliveries": 1000, "availability_queries": 100, "proposals": 0 }, "data": [ { "period": "2026-09", "period_start": "2026-09-01T00:00:00.000Z", "period_end": "2026-09-30T23:59:59.000Z", "is_current": false, "metrics": { "api_calls": 400, "events": 30, "webhook_deliveries": 100, "availability_queries": 20, "proposals": 0, "holds_created": 0, "holds_confirmed": 0, "holds_expired": 0, "cross_calendar_queries": 0 } }, { "period": "2026-10", "period_start": "2026-10-01T00:00:00.000Z", "period_end": "2026-10-31T23:59:59.000Z", "is_current": true, "metrics": { "api_calls": 100, "events": 10, "webhook_deliveries": 50, "availability_queries": 5, "proposals": 0, "holds_created": 0, "holds_confirmed": 0, "holds_expired": 0, "cross_calendar_queries": 0 } } ]}Response fields
Section titled “Response fields”| Field | Description |
|---|---|
plan | Your current plan |
months | Number of entries in data |
limits | Your current plan’s limit for api_calls, events, webhook_deliveries, availability_queries and proposals. null means unlimited and 0 means not included. Past months are not re-evaluated against the plan you had then |
data[].period | The UTC calendar month, YYYY-MM |
data[].period_start, data[].period_end | ISO-8601 first and last second of that month (UTC) |
data[].is_current | true only for the last entry, the month in progress |
data[].metrics | Totals for the month. A month with no activity reports 0 for every counter. Webhook deliveries are webhook_deliveries here (the webhooks field of GET /v1/usage) |
API call totals can lag by up to 30 seconds.
Alerts
Section titled “Alerts”Chronary emails the account owner when a monthly limit reaches 50%, 80%, 90% and 95%, and once more when the limit is reached on a plan where requests are rejected at the limit. This covers api_calls, events, webhook_deliveries, availability_queries and proposals. Each threshold is announced once per metric per month, and only the highest threshold reached is announced.
- Alerts for
events,webhook_deliveries,availability_queriesandproposalscan arrive up to 15 minutes after the threshold is crossed. - Plans that are served past their limit get one notice per metric per month when the limit is passed.
- On a plan where the
eventslimit is a hard stop, public booking pages stop taking bookings at 80% of it, and the owner gets one email that month when the first booking is turned away. - The owner can turn usage alert emails off under Settings → Notifications in the console. Security, billing and account emails are always sent.
Agents do not need email: subscribe a webhook to usage.threshold_crossed to be told at each threshold. That event is sent whether or not alert emails are on.