Get usage

GET/usage

Returns compute used this calendar month, every plan cap with its current count, and your plan's API limits. Call it to size your program's concurrency and to see how close you are to a cap.

Scope	Heavy call	Long poll	CLI
`scripts:read`	No	No	`chartnaut usage`

Guidance

Read api_limits before fanning out. Keep heavy calls in flight at or below concurrent_heavy and long polls at or below concurrent_waits, and you will not see 429 busy from your own program.
caps.concurrent_runs.used counts runs executing right now from the app and the API together. If it sits at its limit, the Agent or a study in the app is using your runs at once, and new API runs wait in queued.
Check caps.definitions, caps.studies and caps.events before Create a script or Run a definition over history, which answer 403 plan_limit at a cap.
compute_units.included is always null: nothing is charged yet. used counts API runs started this month.
history_start is the earliest time a run can reach. A window that starts earlier is moved forward to it.

Response

200 with:

Field	Type	Description
`plan`	string	`free`, `starter`, `pro` or `ultra`
`period`	object	`start` and `end` of this calendar month, UTC. `end` is the first instant of next month
`compute_units`	object	`used`: compute units used by API runs started this month, where 1 unit is 1,000 bars evaluated. `included`: always `null`
`caps`	object	Each plan cap with its current count. Keys below
`history_start`	string	The earliest time your plan's history reaches
`memory_bars`	integer	Your plan's indicator memory in bars
`api_limits`	object	Your plan's API limits. Fields below

caps object

Each key is an object {used, limit}. used is an integer; limit is an integer, or null when the cap is unlimited.

Key	Counts
`indicators`	Your custom indicators, against your library limits
`definitions`	Your definitions
`studies`	Your studies
`events`	Stored definition events across all your definitions
`concurrent_runs`	Runs executing for your account right now, from the app and the API, against your runs at once

api_limits object

Field	Type	Description
`requests_per_minute`	integer	Calls a minute across all your keys
`concurrent_heavy`	integer	Heavy calls in flight at once
`concurrent_waits`	integer	Long polls holding at once

Status codes

Status	Code	Meaning
`200`	-	Usage and limits for your account
`500`	`internal`	Your plan could not be read. Retry

Example request

curl https://api.chartnaut.com/v1/usage \
  -H "Authorization: Bearer cn_live_XXXX"

Example response

200 OK

{
  "plan": "pro",
  "period": {
    "start": "2026-09-01T00:00:00Z",
    "end": "2026-10-01T00:00:00Z"
  },
  "compute_units": {
    "used": 1843.2,
    "included": null
  },
  "caps": {
    "indicators": { "used": 7, "limit": null },
    "definitions": { "used": 12, "limit": 50 },
    "studies": { "used": 31, "limit": 1000 },
    "events": { "used": 18220, "limit": 50000 },
    "concurrent_runs": { "used": 1, "limit": 3 }
  },
  "history_start": "2015-02-02T00:00:00Z",
  "memory_bars": 5000,
  "api_limits": {
    "requests_per_minute": 300,
    "concurrent_heavy": 3,
    "concurrent_waits": 6
  }
}

500 Internal Server Error

{
  "error": {
    "code": "internal",
    "message": "Internal error. Retry; if it persists contact [email protected]."
  }
}

From the CLI

chartnaut usage
chartnaut usage --json

usage prints the period, compute units, caps, history start and memory bars; the API limits appear only with --json. Command reference