Skip to content
GitmoapAPIBeta
Agentsai-org
GET/groups/{group_id}/ai-org/usage

What the organization spent and where: by agent, squad, ritual, model and day, against its

get_ai_org_usage

For anyone who can see the organization (ai_org.view); a period longer than 92 days, or one that ends before it starts, is refused.

Parameters

Path
  • group_idGroupId (string · uuid)The organization's top-level group
Query
  • fromstringoptionalThe period's start, RFC 3339; the month's first day when omitted
  • tostringoptionalThe period's end, RFC 3339; now when omitted

Responses

200The organization's spendapplication/json
  • by_agentarray of AiSpendLineBy agent, the costliest first.
    • The AiSpendLine schema
    • keystringWhat the line is: an agent's handle, a squad's key, a ritual's key, a model or a day.
    • microsinteger · int64What it cost, in millionths of a dollar with the fee included.
    • sessionsinteger · int64How many sessions it was.
  • by_dayarray of AiSpendLineBy UTC day, oldest first.
    • The AiSpendLine schema
    • keystringWhat the line is: an agent's handle, a squad's key, a ritual's key, a model or a day.
    • microsinteger · int64What it cost, in millionths of a dollar with the fee included.
    • sessionsinteger · int64How many sessions it was.
  • by_modelarray of AiSpendLineBy model, the costliest first.
    • The AiSpendLine schema
    • keystringWhat the line is: an agent's handle, a squad's key, a ritual's key, a model or a day.
    • microsinteger · int64What it cost, in millionths of a dollar with the fee included.
    • sessionsinteger · int64How many sessions it was.
  • by_ritualarray of AiSpendLineBy ritual, the costliest first.
    • The AiSpendLine schema
    • keystringWhat the line is: an agent's handle, a squad's key, a ritual's key, a model or a day.
    • microsinteger · int64What it cost, in millionths of a dollar with the fee included.
    • sessionsinteger · int64How many sessions it was.
  • by_squadarray of AiSpendLineBy squad, the costliest first.
    • The AiSpendLine schema
    • keystringWhat the line is: an agent's handle, a squad's key, a ritual's key, a model or a day.
    • microsinteger · int64What it cost, in millionths of a dollar with the fee included.
    • sessionsinteger · int64How many sessions it was.
  • merged_changesinteger · int64The agents' merge requests merged in the period.
  • month_forecast_microsinteger · int64This month's spend at the rate so far, projected to the month's end.
  • month_spent_microsinteger · int64What the organization has spent this calendar month.
  • period_fromstring · date-timeThe period's start.
  • period_tostring · date-timeThe period's end.
  • sessionsinteger · int64How many sessions started in the period.
  • total_microsinteger · int64What the sessions started in the period cost, in millionths of a dollar with the fee.
  • cache_hit_ratenumber · double or nulloptionalThe share of input tokens read from the prompt cache, 0 to 1.
  • cost_per_merged_change_microsinteger · int64 or nulloptionalThe period's spend over its merged changes.
  • monthly_cap_microsinteger · int64 or nulloptionalThe organization's monthly budget, from its live revision.
200 exampleSynthesized example
{
"by_agent": [
{
"key": "key-6bcc",
"micros": 37,
"sessions": 40
}
],
"by_day": [
{
"key": "key-cf00",
"micros": 88,
"sessions": 39
},
{
"key": "key-ccf2",
"micros": 61,
"sessions": 69
}
],
"by_model": [
{
"key": "key-f93a",
"micros": 89,
"sessions": 33
}
],
"by_ritual": [
{
"key": "key-81b5",
"micros": 61,
"sessions": 82
}
],
"by_squad": [
{
"key": "key-da25",
"micros": 35,
"sessions": 73
}
],
"merged_changes": 0,
"month_forecast_micros": 56,
"month_spent_micros": 29,
"period_from": "2026-10-11T09:27:27Z",
"period_to": "2026-10-09T21:24:18Z",
"sessions": 43,
"total_micros": 1,
"cache_hit_rate": 8,
"cost_per_merged_change_micros": 85,
"monthly_cap_micros": 36
}
400application/json
Error codes
  • BAD_REQUESTThe request is malformed: a parameter or a body field is not a well-formed value of its type
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
400 exampleSynthesized example
{
"error": {
"code": "code-634f",
"message": "Pin a page's payload to the build that rendered it"
}
}
401Unauthenticated — no credential, or an invalid oneapplication/json
Error codes
  • UNAUTHORIZEDNo credential was sent, or the one sent is invalid, expired or revoked
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
401 exampleSynthesized example
{
"error": {
"code": "code-ea24",
"message": "Label every synthesized example"
}
}
403Forbidden — the caller's access level or token scope is insufficientapplication/json
Error codes
  • FORBIDDENYou are signed in but may not do this here; reason names the permission or the rule that refused it
  • INSUFFICIENT_SCOPEThe access token lacks the scope this operation needs; required_scope names it
  • PERMISSION_REQUIREDYou need a permission you do not hold here; the message names it
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
403 exampleSynthesized example
{
"error": {
"code": "code-871f",
"message": "Stream pipeline status into the run header"
}
}
404application/json
Error codes
  • NOT_FOUNDThe resource does not exist — or exists and you cannot see it: a private resource you have no access to answers exactly as an absent one does
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
404 exampleSynthesized example
{
"error": {
"code": "code-884d",
"message": "Draw the region map from operation density"
}
}

CLI

gitmoap ai-org get-ai-org-usage

  • --group-ididThe organization's top-level group (id or group path)
  • --fromstringoptionalThe period's start, RFC 3339; the month's first day when omitted
  • --tostringoptionalThe period's end, RFC 3339; now when omitted