> ## Documentation Index > Fetch the complete documentation index at: https://docs.ergoly.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get usage > `?window=30d` and `?days=30` ask the same question; either is accepted. Longer than 90 days is clamped to 90. `?tz=` must be an IANA name and decides where a day starts; it defaults to `UTC`. A zone this system does not recognize is refused rather than swapped for the default. ## OpenAPI ````yaml /openapi.json get /api/v1/usage openapi: 3.1.0 info: title: Ergoly platform API version: 1.0.0 description: >- Read and change one organization's own Ergoly environment. Every route is scoped to the organization the presented credential resolves to; there is no parameter that widens it. The human-readable reference is served from the same namespace at `/api/v1/docs`, behind the same credential. The namespace's front door is `GET /api/v1`, and it is deliberately absent from `paths` below. It answers without a credential — what this API is, how an organization admin mints a key, and where the reference lives — so it is the way in to this contract rather than a part of it: it has no scope, takes no parameters, and there is nothing about it for a generated client to call. Every `unauthorized` refusal carries that same URL as `error.docs`. servers: - url: https://control.ergoly.ai security: - orgApiKey: [] tags: - name: auth description: How to present a key, what it is scoped to, and what a 401 means. - name: organization description: Which organization your credential resolves to. - name: workers description: The Slack apps and bot identities in your organization. - name: eworks description: The runtime instances under a Worker — one core, one per bound Client. - name: clients description: The customers a Worker can be scoped to, and how to bind one. - name: channels description: Which Slack rooms a Worker answers in, and who it answers as. - name: tasks description: >- Tasks handed between Workers and people, scheduled jobs, their targets, and their run history. - name: jobs description: How a provisioning run is going — the other half of every 202. - name: memory description: Read and write the memory tiers an ework mounts. - name: connections description: The credentials your agents use, and the hosts they are injected on. - name: webhooks description: Inbound URLs an outside system can POST to, each of which starts a turn. - name: activity description: Your organization's audit feed. - name: usage description: Cost, turn outcomes and a per-day pulse over a window you choose. - name: errors description: The closed set of refusal codes, and what to do about each. paths: /api/v1/usage: get: tags: - usage summary: Get usage description: >- `?window=30d` and `?days=30` ask the same question; either is accepted. Longer than 90 days is clamped to 90. `?tz=` must be an IANA name and decides where a day starts; it defaults to `UTC`. A zone this system does not recognize is refused rather than swapped for the default. operationId: getUsage parameters: - name: window in: query required: false description: >- `30d`, `7d`, … Defaults to 30 days. Longer than 90 days is clamped to 90. schema: type: string description: >- `30d`, `7d`, … Defaults to 30 days. Longer than 90 days is clamped to 90. - name: days in: query required: false description: The same question spelled as a number. Either form is accepted. schema: type: integer description: The same question spelled as a number. Either form is accepted. - name: tz in: query required: false description: IANA zone the day buckets are folded in. Defaults to `UTC`. schema: type: string description: IANA zone the day buckets are folded in. Defaults to `UTC`. responses: '200': description: Success. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Usage' required: - data additionalProperties: false example: data: generatedAt: '2026-03-04T12:00:00.000Z' rollupAsOf: '2026-03-04T11:00:00.000Z' organizationId: 0d4c9f2e-4b8a-4a5b-9e21-6f9c2a1b7d30 tz: UTC window: days: 30 start: '2026-02-03T00:00:00.000Z' end: '2026-03-05T00:00:00.000Z' cost: costDaytonaUsd: 41.62 costFlyUsd: 3.1 costGithubUsd: 0.84 costWebSearchUsd: 2.05 costLettaUsd: null costTokensUsd: 18.44 costVercelUsd: null costGitUsd: null totalUsd: 66.05 tokenCoverage: turnsWithTokens: 412 turnCount: 1188 fraction: 0.3468013468013468 turns: total: 1188 judged: 1150 ok: 1102 failed: 31 silent: 17 listenSuppressed: 22 incomplete: 16 successRate: 0.9582608695652174 failureRate: 0.041739130434782605 activity: conversationsNew: 96 conversationsActive: 214 taskRuns: 60 taskRunsFinished: 59 taskRunsFailed: 1 agentTimeMs: 5482910 awakeMs: 19204418 presentMs: 25911002 buckets: - key: '2026-03-03' label: Mar 3 isToday: false conversations: 9 runs: 2 failedRuns: 0 - key: '2026-03-04' label: Mar 4 isToday: true conversations: 6 runs: 2 failedRuns: 1 '400': description: '`invalid_request`' content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: '`unauthorized`' content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: '`rate_limited`' content: application/json: schema: $ref: '#/components/schemas/Error' security: - orgApiKey: - usage:read components: schemas: Usage: type: object description: Your organization's slice of the hourly rollup. properties: generatedAt: type: string format: date-time description: When this answer was computed. rollupAsOf: type: - string - 'null' format: date-time description: Newest hour the read model holds — how fresh these numbers are. organizationId: type: string description: Always your own organization. tz: type: string description: The IANA zone the day buckets were folded in. window: type: object description: >- The window these numbers actually cover — every scalar below is folded over exactly this range, so a scalar is the sum of the buckets beside it. properties: days: type: integer description: How many local days the window covers. start: type: string format: date-time description: First instant summed. end: type: string format: date-time description: Last instant summed. required: - days - start - end additionalProperties: false cost: type: object description: >- Per-provider cost. A NULL IS NOT A ZERO: null means no hour in the window measured that provider, which is a different fact from a measured zero. Cost is frozen at the hour it was measured. properties: costDaytonaUsd: type: - number - 'null' description: Sandbox compute. costFlyUsd: type: - number - 'null' description: Egress gateway share. costGithubUsd: type: - number - 'null' description: Memory-tier repository share. costWebSearchUsd: type: - number - 'null' description: Priced web searches. costLettaUsd: type: - number - 'null' description: 'Null: billed fleet-wide with no per-organization dimension.' costTokensUsd: type: - number - 'null' description: >- Model tokens, over the turns that reported them — a lower bound on the spend, not a total. See `tokenCoverage`. costVercelUsd: type: - number - 'null' description: 'Null: billed fleet-wide.' costGitUsd: type: - number - 'null' description: 'Null: billed fleet-wide.' totalUsd: type: - number - 'null' description: Sum of the above, preserving absence. tokenCoverage: type: object description: >- An UPPER bound on how much of the window's traffic is inside `costTokensUsd`, never an exact one, because coverage counts turns that reported something rather than turns that reported everything. Read the cost without this and you will take part of the traffic for the whole bill; read it with this and it is a lower bound on the spend. properties: turnsWithTokens: type: integer description: >- Turns in the window that reported token counts — something, not necessarily everything. A turn whose per-run reads did not all land inside the collection budget reports the ones that did, so it counts here while its counts are short. turnCount: type: integer description: Every turn in the window — the denominator. fraction: type: - number - 'null' description: >- `turnsWithTokens / turnCount`, or null when no turn ran at all. required: - turnsWithTokens - turnCount - fraction additionalProperties: false required: - costDaytonaUsd - costFlyUsd - costGithubUsd - costWebSearchUsd - costLettaUsd - costTokensUsd - costVercelUsd - costGitUsd - totalUsd - tokenCoverage additionalProperties: false turns: type: object description: Turn outcomes over the window. properties: total: type: integer description: Every turn dispatched in the window. judged: type: integer description: >- `ok + failed + silent` — the rate's denominator and its sample size. ok: type: integer description: Turns that answered. failed: type: integer description: An error frame, or a dispatch that failed outright. silent: type: integer description: Ended with nothing in front of the user and no stated reason. listenSuppressed: type: integer description: The reply could never post, by design. Excluded from `judged`. incomplete: type: integer description: No terminal status arrived. Excluded from `judged`. successRate: type: - number - 'null' description: >- `ok / judged`, or null when nothing has been judged. Never 0 for an empty set. failureRate: type: - number - 'null' description: >- `(failed + silent) / judged`, carried so a caller does not invert the rate and disagree in the last decimal. required: - total - judged - ok - failed - silent - listenSuppressed - incomplete - successRate - failureRate additionalProperties: false activity: type: object description: Counters over the window. Durations preserve absence. properties: conversationsNew: type: integer description: Conversations first seen in the window. conversationsActive: type: integer description: Conversations with traffic in the window. taskRuns: type: integer description: Scheduled runs started. taskRunsFinished: type: integer description: Runs that reached a terminal state. taskRunsFailed: type: integer description: Runs that failed. agentTimeMs: type: - integer - 'null' description: Agent time. Null means no hour measured it. awakeMs: type: - integer - 'null' description: Sandbox awake time. Null means no hour measured it. presentMs: type: - integer - 'null' description: Sandbox present time. Null means no hour measured it. required: - conversationsNew - conversationsActive - taskRuns - taskRunsFinished - taskRunsFailed - agentTimeMs - awakeMs - presentMs additionalProperties: false buckets: type: array items: type: object description: >- One local day. A day crossing a DST boundary collects 23 or 25 hours. properties: key: type: string description: The local date, `YYYY-MM-DD` in `tz`. label: type: string description: A short human label for that day. isToday: type: boolean description: True for the day in progress. conversations: type: integer description: Conversations active that day. runs: type: integer description: Scheduled runs that day. failedRuns: type: integer description: How many of them failed. required: - key - label - isToday - conversations - runs - failedRuns additionalProperties: false description: Per local day, in `tz`. required: - generatedAt - rollupAsOf - organizationId - tz - window - cost - turns - activity - buckets additionalProperties: false Error: type: object description: The one error shape. Every refusal in this namespace has it. properties: error: type: object description: The refusal. properties: code: type: string enum: - unauthorized - not_found - invalid_request - conflict - quota_exceeded - rate_limited - upstream_error - gone description: The machine-stable half. Branch on this, never on `message`. message: type: string description: Prose for a human reading a terminal. docs: type: string description: >- Where to learn how to authenticate. Present on `unauthorized` and on nothing else — it is the one refusal a caller can reach with no credential at all, so it is the one that has to say where the way in is. required: - code - message additionalProperties: false required: - error additionalProperties: false securitySchemes: orgApiKey: type: http scheme: bearer description: >- An organization-scoped API key, minted in control under Settings → API keys. Every failure to authenticate answers one identical 401: "Provide a valid organization-scoped API key or an active session." Each operation names the one scope it is filed under, `:`, where the resource is the first path segment after `/api/v1/`; a key minted today carries all 22 of them. Scopes are RECORDED — on the key and on every audit row — and are not yet enforced: no request is refused for want of one. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.