Cost report

⚠️

Preview — this feature is being built; the design below is the spec.

The cost report returns what your organization spent, in US dollars, per day, split by workspace and by line item. It answers finance questions (“what did the support team’s workspace cost last month?”, “how much went on web search?”) and is the number to reconcile against your invoices.

Tokens covered by your plan allowance cost nothing extra and appear here with a cost of zero and billing_source: "subscription", so the report shows both what was used and what was paid for.

Endpoint

GET /v1/organizations/cost_report

Authenticate with an admin key and send syntic-beta: admin-2026-11-01.

Query parameters

Parameter	Required	Description
`starting_at`	Yes	First day, RFC 3339 at midnight UTC.
`ending_at`	No	Exclusive end. Default: now.
`group_by[]`	No	`workspace_id`, `description`, `model`, `billing_source`. Repeat for several.
`workspace_ids[]`	No	Only these workspaces.
`limit`	No	Days per page, 1 to 31, default 7.
`after_id`	No	The `last_id` from the previous response (next page).
`before_id`	No	The `first_id` from the previous response (previous page).

Buckets are always one UTC day.

Response

{
  "data": [
    {
      "starting_at": "2026-11-04T00:00:00Z",
      "ending_at": "2026-11-05T00:00:00Z",
      "results": [
        {
          "workspace_id": "wrkspc_01JC0A2C4E6G8J0L2N4Q",
          "description": "Amara S1.2 output tokens",
          "line_item": "tokens.output",
          "model": "Amara S1.2",
          "billing_source": "api_credit",
          "quantity": "1204011",
          "unit": "token",
          "amount_usd": "14.4481"
        },
        {
          "workspace_id": "wrkspc_01JC0A2C4E6G8J0L2N4Q",
          "description": "Web search",
          "line_item": "server_tool.web_search",
          "model": null,
          "billing_source": "api_credit",
          "quantity": "412",
          "unit": "search",
          "amount_usd": "4.1200"
        }
      ]
    }
  ],
  "has_more": false,
  "first_id": "bkt_01JC7A0B2C4D6E8F",
  "last_id": "bkt_01JC7A0B2C4D6E8F"
}

Field	Meaning
`description`	A readable label, stable enough to group on.
`line_item`	A stable machine name: `tokens.input`, `tokens.cached_input`, `tokens.output`, `server_tool.web_search`, `server_tool.web_fetch`, `code_execution.container_seconds`, `memory.storage`, `batch.tokens.input`, `batch.tokens.output` and so on. New line items may be added.
`billing_source`	`subscription` (covered by the plan, `amount_usd` is `0`) or `api_credit`.
`quantity`, `unit`	How much was used, as a decimal string.
`amount_usd`	Cost as a decimal string with 4 decimal places.

Not included: plan subscription fees, credit purchases, taxes and refunds. Those are on your invoices in Billing.

Reconciling with invoices

Summing amount_usd for a calendar month gives the usage-credit charges for that month, to within a cent per line of rounding. Costs for a day are final 24 hours after the day ends; until then the latest day can change.

Examples

# Last month by workspace and line item, as CSV
curl -sS -G https://app.syntic.ai/v1/organizations/cost_report \
  -H "Authorization: Bearer $SYNTIC_ADMIN_KEY" \
  -H "syntic-beta: admin-2026-11-01" \
  --data-urlencode "starting_at=2026-10-01T00:00:00Z" \
  --data-urlencode "ending_at=2026-11-01T00:00:00Z" \
  --data-urlencode "group_by[]=workspace_id" \
  --data-urlencode "group_by[]=description" \
  --data-urlencode "limit=31" \
| jq -r '.data[] | .starting_at as $d | .results[] | [$d, .workspace_id, .description, .amount_usd] | @csv'

const qs = new URLSearchParams([
  ['starting_at', '2026-10-01T00:00:00Z'], ['ending_at', '2026-11-01T00:00:00Z'],
  ['group_by[]', 'workspace_id'], ['limit', '31'],
])
const res = await fetch(`https://app.syntic.ai/v1/organizations/cost_report?${qs}`, {
  headers: { Authorization: `Bearer ${process.env.SYNTIC_ADMIN_KEY}`, 'syntic-beta': 'admin-2026-11-01' },
})
const { data } = await res.json()
const totals = {}
for (const day of data) for (const r of day.results) {
  totals[r.workspace_id] = (totals[r.workspace_id] ?? 0) + Number(r.amount_usd)
}
console.log(totals)

import os, requests
from decimal import Decimal
from collections import defaultdict
 
r = requests.get(
    "https://app.syntic.ai/v1/organizations/cost_report",
    headers={"Authorization": f"Bearer {os.environ['SYNTIC_ADMIN_KEY']}", "syntic-beta": "admin-2026-11-01"},
    params={"starting_at": "2026-10-01T00:00:00Z", "ending_at": "2026-11-01T00:00:00Z",
            "group_by[]": ["workspace_id"], "limit": 31},
)
totals = defaultdict(Decimal)
for day in r.json()["data"]:
    for row in day["results"]:
        totals[row["workspace_id"]] += Decimal(row["amount_usd"])
for ws, usd in sorted(totals.items(), key=lambda kv: -kv[1]):
    print(ws, f"${usd:.2f}")

Errors

Errors use the error envelope.

Status	`type`	`code`	When
400	`invalid_request_error`	`invalid_time_range`	`starting_at` missing, not at midnight UTC, or after `ending_at`.
400	`invalid_request_error`	`invalid_group_by`	Unknown grouping dimension.
403	`permission_error`	`admin_key_required`	An inference key was used.

Build notes for the platform team

Build from the same usage rows and rate table that produce wallet debits, so the report and the wallet cannot disagree.
Add a line_item on every new billable feature (web search, code execution, memory storage) in its first release.
Reconcile monthly totals against the payment provider’s invoices in an automated check.

Get the usage report Get the cost report

Was this page helpful?