curl --request GET \
--url https://davinci-app.com/api/v2/usage \
--header 'Authorization: Bearer <token>'import os
from davinci_sdk import DavinciClient
with DavinciClient(api_key=os.environ["DAVINCI_API_KEY"]) as client:
usage = client.usage.get(group_by="model")
for row in usage.groups or []:
print(row.model, row.credits)
import { DavinciClient } from '@celedon/davinci-sdk';
const client = new DavinciClient({
apiKey: process.env.DAVINCI_API_KEY!,
});
const usage = await client.usage.get({ groupBy: 'model' });
for (const row of usage.groups ?? []) {
console.log(row.model, row.credits);
}
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://davinci-app.com/api/v2/usage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"scope": "account",
"asOf": "2023-11-07T05:31:56Z",
"totals": {
"credits": 123,
"promptTokens": 123,
"completionTokens": 123,
"reasoningTokens": 123,
"cacheWriteTokens": 123,
"cacheReadTokens": 123,
"eventCount": 123
},
"projectId": "<string>",
"sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"groupBy": "model",
"groups": [
{
"credits": 123,
"promptTokens": 123,
"completionTokens": 123,
"reasoningTokens": 123,
"cacheWriteTokens": 123,
"cacheReadTokens": 123,
"eventCount": 123,
"provider": "<string>",
"model": "<string>",
"projectId": "<string>",
"sessionId": "<string>",
"day": "2023-11-07T05:31:56Z"
}
]
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}What you spent
Credits and tokens charged to your account, optionally narrowed by project, session, or time, and optionally broken down by model, project, session, or day.
This reports your own usage. A project you share with collaborators returns what you spent on it, not the project’s total — what someone else spends is their financial data, not the project’s.
Reads are eventually consistent with a live run: the engine reports usage on
an interval, so check asOf before treating a total as final.
curl --request GET \
--url https://davinci-app.com/api/v2/usage \
--header 'Authorization: Bearer <token>'import os
from davinci_sdk import DavinciClient
with DavinciClient(api_key=os.environ["DAVINCI_API_KEY"]) as client:
usage = client.usage.get(group_by="model")
for row in usage.groups or []:
print(row.model, row.credits)
import { DavinciClient } from '@celedon/davinci-sdk';
const client = new DavinciClient({
apiKey: process.env.DAVINCI_API_KEY!,
});
const usage = await client.usage.get({ groupBy: 'model' });
for (const row of usage.groups ?? []) {
console.log(row.model, row.credits);
}
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://davinci-app.com/api/v2/usage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"scope": "account",
"asOf": "2023-11-07T05:31:56Z",
"totals": {
"credits": 123,
"promptTokens": 123,
"completionTokens": 123,
"reasoningTokens": 123,
"cacheWriteTokens": 123,
"cacheReadTokens": 123,
"eventCount": 123
},
"projectId": "<string>",
"sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"groupBy": "model",
"groups": [
{
"credits": 123,
"promptTokens": 123,
"completionTokens": 123,
"reasoningTokens": 123,
"cacheWriteTokens": 123,
"cacheReadTokens": 123,
"eventCount": 123,
"provider": "<string>",
"model": "<string>",
"projectId": "<string>",
"sessionId": "<string>",
"day": "2023-11-07T05:31:56Z"
}
]
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"details": {}
}
}Authorizations
Personal access token. The scopes granted at issuance determine both which
operations the key may call and the ceiling on the resource permissions it
can exercise. Each scope family is a ladder: projects:manage implies
projects:write and projects:read; cards:manage implies cards:write
and cards:read; and teams:manage implies teams:write and teams:read.
These are named API capability bundles, not blanket domain roles:
manage exposes only the permissions enumerated for that scope and never
bypasses the acting user's current role-based access.
Query Parameters
Narrow to one project. Accepts the bare id or {projectId}--{branch}.
Narrow to one session.
Only count events at or after this time. Omit for all of recorded history.
Only count events at or before this time.
Break the totals down. Omit to receive totals only — totals is always
present and always covers the whole scope, whether or not you group.
model, project, session, day Response
Usage totals for the scope, and the breakdown if one was asked for.
What the numbers cover, determined by the path you called.
account, project, session When the newest counted event was recorded, or null when the scope holds none. This is the honest bound on freshness: the engine reports usage on an interval, so a run's last few seconds may not be included. Null means "nothing here", not "nothing yet" — a scope with no usage looks the same either way, and inventing a timestamp would hide that.
Hide child attributes
Hide child attributes
Credits charged, to six decimal places.
Thinking tokens, charged at the completion rate.
Charged calls counted. Not all of them are token-priced — image generation
and web search are charged per call, so a non-zero credits with zero
tokens is normal rather than a gap.
Present on the project and session reads. Always the bare id.
Present on the session read.
Echoed back when you asked for a breakdown.
model, project, session, day One entry per group, largest spend first — except day, which is
chronological. Absent unless you passed groupBy.
Hide child attributes
Hide child attributes
Credits charged, to six decimal places.
Thinking tokens, charged at the completion rate.
Charged calls counted. Not all of them are token-priced — image generation
and web search are charged per call, so a non-zero credits with zero
tokens is normal rather than a gap.
Present when grouping by model.
Present when grouping by model.
Present when grouping by project.
Present when grouping by session.
Midnight UTC of the day. Present when grouping by day.