GET/api/v1/usage/me

Get My Usage

Return current user's aggregate usage + quota for the current billing month.

Uses existing APIUsageHourly.call_count aggregation (no new tables required for Phase 1). Task telemetry is retained for dashboard visibility but does not gate monthly quota.

Request example

json

{
  "tasks": [
    {
      "id": "T1",
      "duration_days": 5
    }
  ]
}

Response example

json

{
  "score": 92,
  "grade": "A"
}

Response fields from OpenAPI contract

This table is generated from the endpoint response schema in openapi.json.

Field	Type	Required	Description
user_id	string	Required	User ID
tier	string	Required	Current account tier
period	object	Required	Billing period window (UTC month boundaries).
period.start	string	Required	Period start (UTC)
period.end	string	Required	Period end (UTC)
task_telemetry	object	Optional	Task analytics for the month. Informational; tasks do not gate the monthly quota.
task_telemetry.processed_this_month	integer	Optional	Tasks processed this month
task_telemetry.avg_tasks_per_call	number	Optional	Average tasks per call
task_telemetry.per_request_limit	integer	Optional	Maximum tasks in one request
task_telemetry.payload_limit_mb_per_request	integer	Optional	Maximum request size in MB
calls	object	Required	Monthly call quota.
calls.used	integer	Required	Calls this billing month
calls.limit	integer	Required	Monthly call quota
calls.pct	number	Required	Percent of the quota used
calls.overage_calls	integer	Required	Calls above the quota
calls.overage_allowed	boolean	Required	True when calls above the quota are billed instead of refused
keys	array<unknown>	Optional	Per-key breakdown
keys[].key_id	string	Optional	API key ID (UUID)
keys[].prefix	string	Optional	Key prefix (first 8 chars visible)
keys[].tasks	integer	Optional	Tasks processed by this key this month
keys[].calls	integer	Optional	API calls made by this key this month
keys[].last_used	string \| null	Optional	Last usage timestamp
warnings	array<unknown>	Optional	Quota warning objects (70%/90% thresholds)
warnings[].type	string	Optional	approaching_quota (70%) or quota_critical (90%)
warnings[].metric	string	Optional	Metered quantity, currently always calls
warnings[].threshold	number	Optional	Threshold crossed, as a fraction
warnings[].current_pct	number	Optional	Percent of the quota used

Schema

json-schema

{
  "$ref": "#/components/schemas/UsageMeResponse"
}

Authentication

API key required

Reference details

Operation ID: get_my_usage
Section: Usage & Quota
Tags: Usage & Quota

Was this page helpful?

Your feedback helps us improve docs, reference pages, and Playground flows.

Topic: Get My Usage · Page: /docs/api-reference/get_my_usage

Report an issue Suggest improvement

Terms Privacy Contact

Schedule analysis guidance. Not legal advice. You remain responsible for contract and agency compliance.