Docs

Start here

Where the credits went this month

GET/v1/usageon https://api.auray.ai/v1

By product AND by origin, so you can tell your script from your team's browser.

By product AND by origin, so you can tell your script from your team's browser. Origin is read from the debit that paid for a job: a refund does not record which surface made it.

#Authentication

Authorization: Bearer auray_sk_… — Any key. The read bucket paces it.

#Request

#Query parameters

NameTypeRequiredDescription
windowstringnoThe window report covers: this calendar month (the default), the last one, the last ninety days, or the last twelve months. One of "month", "last_month", "90d", "12m".
formatstringnocsv answers one row per charged job in the window — what it cost, what came back and the key it went through — instead of the document. One of "json", "csv".

#Example request

curl https://api.auray.ai/v1/usage \
  -H "Authorization: Bearer $AURAY_API_KEY"

#Responses

#200 OK

OK

FieldTypeRequiredDefaultDescription
objectstringno—One of "usage".
periodstringno—
windowstringno—The window report covers. One of "month", "last_month", "90d", "12m".
creditsobjectno—
credits.balanceintegerno—
credits.monthly_allowanceintegerno—
credits.spent_this_periodintegerno—
credits.refunded_this_periodintegerno—
credits.net_this_periodintegerno—
credits.waived_this_periodintegerno—Credits a promotion covered this period, at the price each job was charged. Jobs a promotion covers write no ledger row, so they are counted here and not in spent_this_period.
credits.waived_jobs_this_periodintegerno—How many jobs a promotion covered this period.
by_productobject[]no—
by_product[].productstringno—Every product the credit ledger can charge, which is wider than the Product enum used elsewhere: usage sums the whole shared ledger. external is every model somebody else runs, submitted by its address; embeddings is POST /embeddings on the OpenAI-compatible server; the desktop's Code product charges it too, and there is no POST /code — code can be spent, but not submitted from this API. director is the AI Director's rounds in a Cinema Studio project, spent from the desktop and not submitted from this API; what it starts is charged to each model's own product. The monthly grant is not a product here; it is credits.monthly_allowance. One of "photo", "music", "video", "threed", "external", "chat", "code", "embeddings", "director".
by_product[].originstringno—Whether the credits went to a script or to the desktop, read from the debit that paid for the job. ui is the jobs tables' word for app and never reaches this field. The ledger's third origin, admin, marks an adjustment of ours, which is booked to the non-spendable platform product and so never appears in this list. One of "api", "app".
by_product[].spentintegerno—
by_product[].refundedintegerno—
by_product[].netintegerno—
by_product[].jobsintegerno—
by_product[].waivedintegerno—Credits a promotion covered for this product and origin.
by_product[].waived_jobsintegerno—Jobs a promotion covered for this product and origin.
keysobject[]no—Your secret API keys, most recently used first and never-used ones last, at most 100, revoked ones included: each carries credits_spent_period against its own ceiling (credit_ceiling, null when the key has none). The desktop's own session keys are not listed.
keys_truncatedbooleanno—True when you hold more than 100 secret keys, so keys is not all of them. The ones left out are the least recently used; the credit figures above are summed from the ledger and still count every key.
rate_limitsobjectno—Each bucket this key is admitted from — read, write, generate, interactive and egress — as {capacity, refill_per_second}, at the strength the key is admitted at now: the plan's figures in force, and during the account's warm-up — the plan's own hours after sign-up — its warm-up share of them (limits.api.warmup on GET /v1/plans; see warmup_ends_at). egress is in megabytes. A capacity of zero is a bucket the plan does not have.
warmup_ends_atstringno—When the account's warm-up ends — its plan's warm-up hours after sign-up — and rate_limits steps up to the plan's full figures; null once it has, or when the plan has no warm-up. May be null.
reportobjectno—The one usage document — what Account > Usage draws, for window: totals, products, origins, a series, keys, models, the language models' tokens, the balance's purchased and granted parts, the promotion seat, and the platform's grants and adjustments. Every figure is read from the credit ledger; one that could not be read is 503 usage_unavailable, never a zero.
notestringno—The caveat that belongs beside these figures: origin is taken from the debit that paid for a job, because a refund does not record which surface made it, and the numbers cover the current calendar month.

Headers:

HeaderDescription
RateLimit-LimitBurst capacity.
RateLimit-Remaining
RateLimit-ResetSeconds until refill.
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-ResetUnix seconds. The X- spelling is what client libraries read.
X-Request-Id

#400 Bad Request

#401 Unauthorized

#403 Forbidden

#413 Payload Too Large

export_too_large — the CSV for this window would carry more debits than one file holds. Or usage_window_too_large — the document for this window would read more of your ledger than one request is given time for. Either is the window, not a failed read: ask for a narrower one.

The error body: error, message, docs (the entry that explains it) and request_id.

#429 Too Many Requests

#500 Internal Server Error

profile_read_failed — the plan your account holds could not be resolved, so the allowance could not be stated.

The error body: error, message, docs (the entry that explains it) and request_id.

#503 Service Unavailable

usage_unavailable — the ledger, the wallet or the usage report could not be read. Reported rather than guessed: a failed read used to become totals of zero, on a page entirely about money.

The error body: error, message, docs (the entry that explains it) and request_id.

#Status codes

StatusMeaning
200OK
400Bad Request
401Unauthorized
403Forbidden
413export_too_large — the CSV for this window would carry more debits than one file holds.
429Too Many Requests
500profile_read_failed — the plan your account holds could not be resolved, so the allowance could not be stated.
503usage_unavailable — the ledger, the wallet or the usage report could not be read.

Every refusal names its code, and every code is explained at Errors.

Start typing to search every page of the documentation.

Up arrow Down arrow to moveEnter to openEscape to close