Your API key:

All requests below will use this key. Your API key is sent directly to api.cueapi.ai and never stored by the docs site.

GET/v1/usage

Usage Stats

Get current plan, billing period, cue count, execution usage, projections, and rate limit info.

Request

bash

curl https://api.cueapi.ai/v1/usage \
  -H "Authorization: Bearer cue_sk_YOUR_KEY"

Response

json

{
  "plan": "free",
  "billing_period": {
    "start": "2026-03-01",
    "end": "2026-03-31",
    "days_remaining": 14
  },
  "cues": {
    "used": 4,
    "limit": 10,
    "remaining": 6,
    "percent_used": 40
  },
  "executions": {
    "used": 127,
    "limit": 300,
    "remaining": 173,
    "percent_used": 42,
    "projected_month_end": 381,
    "will_exceed_limit": true
  },
  "outcomes": {
    "reported": 38,
    "succeeded": 35,
    "failed": 3
  },
  "rate_limit": {
    "requests_per_minute": 60,
    "current_usage": 3
  },
  "upgrade_url": "https://dashboard.cueapi.ai/billing"
}

Response fields

Field	Type	Description
`plan`	string	Current plan: `free`, `pro`, or `scale`
`billing_period.start`	string	First day of current billing month (ISO date)
`billing_period.end`	string	Last day of current billing month (ISO date)
`billing_period.days_remaining`	integer	Days until billing period resets
`cues.used`	integer	Number of active + paused cues
`cues.limit`	integer	Maximum cues allowed on current plan
`cues.remaining`	integer	How many more cues can be created
`cues.percent_used`	integer	Percentage of cue limit used (0-100)
`executions.used`	integer	Executions consumed this billing period
`executions.limit`	integer	Maximum executions allowed on current plan
`executions.remaining`	integer	Executions remaining this period
`executions.percent_used`	integer	Percentage of execution limit used (0-100)
`executions.projected_month_end`	integer	Linear projection of total executions by month end
`executions.will_exceed_limit`	boolean	Whether projected usage will exceed the plan limit
`outcomes.reported`	integer	Executions with outcomes reported this month
`outcomes.succeeded`	integer	Successful outcomes this month
`outcomes.failed`	integer	Failed outcomes + delivery failures this month
`rate_limit.requests_per_minute`	integer	Requests per minute allowed on current plan
`rate_limit.current_usage`	integer	Requests made in the current 60-second window
`upgrade_url`	string	Link to billing dashboard for plan upgrades

Agent usage

Agents should check this endpoint before creating new cues or registering high-frequency schedules:

python

usage = requests.get("https://api.cueapi.ai/v1/usage", headers=headers).json()
 
if usage["cues"]["remaining"] <= 0:
    print("No cue slots available. Upgrade or delete unused cues")
 
if usage["executions"]["will_exceed_limit"]:
    print(f"Projected {usage['executions']['projected_month_end']} executions. Will exceed limit")

GET/v1/usage

Try it

Enter your API key above to send requests

Previous← Customer Portal NextHeartbeat →