Spend limits

Spend limits cap how much your organization can be charged in usage credits each calendar month, overall and per workspace, member or group. They already exist in the Console (see Billing & credits and Usage & cost); these endpoints expose the same controls to scripts, so budgets can be set from your finance tooling or infrastructure code and checked automatically.

Spend limits count only spending from usage credits. Tokens covered by your plan allowance never count against them.

Endpoints

Authenticate with an admin key and send syntic-beta: admin-2026-11-01. Changing limits needs a key created by an Owner or Administrator, as in the Console.

Read limits

GET /v1/organizations/spend_limits with optional scope (organization, workspace, member, group) to narrow the list.

{
  "type": "spend_limits",
  "period": { "starting_at": "2026-11-01T00:00:00Z", "ending_at": "2026-12-01T00:00:00Z" },
  "credits_enabled": true,
  "multi_group_policy": "lower",
  "organization": { "monthly_limit_usd": "500.00", "spent_usd": "212.4031" },
  "workspaces": [
    { "workspace_id": "wrkspc_01JC0A2C4E6G8J0L2N4Q", "monthly_limit_usd": "400.00", "spent_usd": "198.1022" },
    { "workspace_id": "wrkspc_01JC5B7D9F1H3K5M7P9R", "monthly_limit_usd": "25.00", "spent_usd": "14.3009" }
  ],
  "groups": [
    { "group_id": "grp_01JB...", "name": "Contractors", "monthly_limit_usd": "20.00" }
  ],
  "members": [
    {
      "user_id": "user_01J9Y0A2C4E6G8J0L2N4",
      "monthly_limit_usd": null,
      "inherited_limit_usd": "20.00",
      "inherited_from_group_id": "grp_01JB...",
      "effective_limit_usd": "20.00",
      "spent_usd": "6.2200"
    }
  ]
}

All money values are decimal strings in US dollars.

Set a limit

PUT /v1/organizations/spend_limits

The response is the updated spend_limits object. Lowering a limit below what has already been spent this month takes effect at once: the next request paid from credits is refused.

# Cap one member at $50 a month
curl -sS -X PUT https://app.syntic.ai/v1/organizations/spend_limits \
  -H "Authorization: Bearer $SYNTIC_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -H "syntic-beta: admin-2026-11-01" \
  -d '{"scope": "member", "user_id": "user_01J9Y0A2C4E6G8J0L2N4", "monthly_limit_usd": "50.00"}'

// Alert when any workspace passes 80% of its cap
const res = await fetch('https://app.syntic.ai/v1/organizations/spend_limits?scope=workspace', {
  headers: { Authorization: `Bearer ${process.env.SYNTIC_ADMIN_KEY}`, 'syntic-beta': 'admin-2026-11-01' },
})
const { workspaces } = await res.json()
for (const w of workspaces) {
  const used = Number(w.spent_usd) / Number(w.monthly_limit_usd)
  if (used >= 0.8) console.warn(`${w.workspace_id} at ${(used * 100).toFixed(0)}% of $${w.monthly_limit_usd}`)
}

import os, requests
 
H = {"Authorization": f"Bearer {os.environ['SYNTIC_ADMIN_KEY']}", "syntic-beta": "admin-2026-11-01"}
 
# Raise the organization cap for a launch week
r = requests.put("https://app.syntic.ai/v1/organizations/spend_limits", headers=H,
                 json={"scope": "organization", "monthly_limit_usd": "2000.00"})
r.raise_for_status()
print(r.json()["organization"])

To be notified instead of polling, subscribe to the spend.threshold_reached webhook, sent at 50%, 80% and 100% of each limit.

Organization options

PATCH /v1/organizations/spend_limits/settings with either or both of:

Auto-reload settings and credit purchases stay in the Console’s Billing page, because they move money.

What callers see when a limit is reached

Requests that would be paid from credits fail with 402:

{
  "error": {
    "type": "quota_exhausted",
    "code": "quota_exhausted",
    "message": "This workspace's monthly spend limit of $25.00 has been reached.",
    "param": null,
    "details": { "limit": "spend_limit", "limit_scope": "workspace", "resets_at": "2026-12-01T00:00:00Z" }
  },
  "request_id": "req_6f1c2a9e0b7d4c3a8e5f1b2d"
}

details.limit_scope (organization, workspace or member) is new; today’s flat error says only limit: "spend_limit".

Errors

Errors use the error envelope.

Build notes for the platform team

• Wrap the existing usage-credit settings function; the enforcement path in the request pipeline does not change, apart from adding the workspace scope.
• Every change writes billing.spend_limit_changed with old and new values.

Related

• Cost report
• Billing & credits
• Control costs
• Limits