/api/orgs/{org_id}/provider-connections/{provider}/spend-refreshRefresh provider account spend
Reads what the provider account reports (spend, remaining credits, limit) and stores it as a snapshot. Inside the provider's staleness floor (5 minutes for most queried providers, 3 hours for Bedrock) the stored reading answers with refreshed: false instead of a new query, so calling it often is safe. OpenAI and Anthropic report only with a stored admin key (spend_secret). Plan accounts are refused with 409.
Authentication: Bearer API key in the Authorization header
Path parameters
org_idstringrequiredYour organization id (uuid).
GET /api/whoamireturns it.providerenumrequiredThe provider to connect.
Query parameters
setup_aliasstringThe account handle. Omitted, the provider-named default account.
Responses
200The refresh outcome.
Response
providerenumrequiredA provider an organization can connect its own key for. kenari, kiosapi, tokenharbor, groq and nvidia_nim are free-tier providers open to every plan.
kindenumrequirednot_reportable: the provider exposes no billing to this credential;read_failed: the message names the failure and fix.refreshedbooleanrequiredFalse when the staleness floor answered from the stored reading.
staleness_floor_secondsintegerrequirednext_refresh_atstring | nullrequiredWhen a fresh query is allowed; null once allowed.
messagestringrequiredsnapshotobject | nullrequiredOne of
object
taken_atstringrequiredsourceenumrequiredprovider_api: the provider's billing API;our_side: AWS Cost Explorer.spend_usdnumber | nullrequiredSpend reported by the provider, in dollars.
credits_remaining_usdnumber | nullrequiredRemaining prepaid balance, in dollars.
usage_limit_usdnumber | nullrequiredAccount usage limit, in dollars.
detailobject | nullrequired
400The request is malformed or names an unsupported value.
Response
errorstringrequiredHuman-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
401Missing, unknown or revoked API key.
Response
errorstringrequiredHuman-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
403The key is valid but may not perform this action (for example an inference key on a provisioning-key route, or a feature outside your plan).
Response
errorstringrequiredHuman-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
404The resource does not exist or belongs to another organization.
Response
errorstringrequiredHuman-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
409The account is a plan account, not an API key.
Response
errorstringrequiredHuman-readable message.
codestringStable machine reason, when the route defines one (for example
pro_required).actionstringStable remediation action, when the route defines one.
detailsobjectCustomer-safe string facts the caller needs to act (for example a suggested identifier).
Request
curl -X POST https://api.experientiallabs.ai/api/orgs/3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10/provider-connections/openai/spend-refresh?setup_alias=openai-main \
-H "Authorization: Bearer YOUR_API_KEY"Response
{
"provider": "openrouter",
"kind": "reported",
"refreshed": true,
"staleness_floor_seconds": 300,
"next_refresh_at": null,
"message": "Read from the OpenRouter key endpoint.",
"snapshot": {
"taken_at": "2026-11-19T14:12:00.120Z",
"source": "provider_api",
"spend_usd": 182.44,
"credits_remaining_usd": 317.56,
"usage_limit_usd": 500,
"detail": null
}
}https://api.experientiallabs.ai/api/orgs/3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10/provider-connections/openai/spend-refresh?setup_alias=openai-main