Skip to content

Usage

Check your organization’s current API call usage, resource counts, and plan limits.

GET /v1/usage

No query parameters required. Returns usage for the authenticated organization.

Terminal window
curl https://api.chronary.ai/v1/usage \
-H "Authorization: Bearer chr_sk_your_key_here"
{
"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 }
}

Every metric is returned as { used, limit }. A null limit means that metric is unlimited on your plan.

FieldDescription
planYour account’s plan: free, free-agent-unverified (agent signup, not yet verified), developer, pro, or scale (the Custom plan)
period_startISO-8601 start of the current quota period (the calendar month, UTC)
period_endISO-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_atISO-8601 first instant of the next UTC month (00:00:00 UTC on the 1st), when the monthly counters reset
generated_atISO-8601 time this response was computed. API calls can lag by up to 30 seconds
agentsCurrent agent count vs plan cap
calendarsCurrent calendar count vs plan cap
eventsEvents created this period vs plan cap
api_callsAPI calls this period vs plan cap
webhooksWebhook deliveries this period vs plan cap
availability_queriesAvailability queries this period vs plan cap
ical_subscriptionsCurrent iCal subscription count vs plan cap
proposalsScheduling proposals created this period vs plan cap
recurring_eventsCurrent active recurring series count vs plan cap (a concurrent cap, not monthly — deleting a series frees its slot)
holdsTemporal-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.

GET /v1/usage/history?months=6

Returns 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 parameterDescription
monthsNumber of months to return, 1 to 12. Defaults to 6. Anything else returns 400 validation_error
Terminal window
curl "https://api.chronary.ai/v1/usage/history?months=3" \
-H "Authorization: Bearer chr_sk_your_key_here"
{
"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
}
}
]
}
FieldDescription
planYour current plan
monthsNumber of entries in data
limitsYour 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[].periodThe UTC calendar month, YYYY-MM
data[].period_start, data[].period_endISO-8601 first and last second of that month (UTC)
data[].is_currenttrue only for the last entry, the month in progress
data[].metricsTotals 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.

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_queries and proposals can 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 events limit 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.