/api/orgs/{org_id}/provider-connections/{provider}/plans/{setup_alias}/refresh-usageRefresh plan account usage
Reads the plan's rolling usage windows now, refreshing the sign-in if it is about to expire, and mirrors them onto the account; a spent window marks it quota_exhausted so traffic rotates to the next account. Never needs Pro. 502 when the provider read fails.
Authentication: Bearer API key in the Authorization header
Path parameters
org_idstringrequiredYour organization id (uuid).
GET /api/whoamireturns it.providerenumrequiredopenaifor ChatGPT plans,anthropicfor Claude plans. Any other provider answers 404.setup_aliasstringrequiredThe plan account handle.
Query parameters
automaticbooleanA live poll; reuses a reading younger than 45 seconds and audits only a verdict change.
Responses
200The plan account after the read.
Response
setup_aliasstringrequiredplanobjectrequiredWhat a plan account carries instead of a key.
plan
labelstringrequiredplan_typestring | nullrequiredFor example plus, pro, team, max.
primaryobject | nullrequiredOne of
object
used_percentintegerrequiredreset_atstring | nullrequiredwindow_minutesinteger | nullrequired
secondaryobject | nullrequiredOne of
object
used_percentintegerrequiredreset_atstring | nullrequiredwindow_minutesinteger | nullrequired
derivedobject | nullOne of
object
five_hourobject | nullrequiredOne of
object
requestsintegerrequiredinput_tokensintegerrequiredcached_input_tokensintegerrequiredoutput_tokensintegerrequiredfirst_activitystring | nullrequiredlast_activitystring | nullrequired
seven_dayobject | nullrequiredOne of
object
requestsintegerrequiredinput_tokensintegerrequiredcached_input_tokensintegerrequiredoutput_tokensintegerrequiredfirst_activitystring | nullrequiredlast_activitystring | nullrequired
checked_atstring | nullrequiredscopeenumorg: the shared pool;account: only API keys created byowner_user_id.owner_user_idstring | nullrotation_pausedbooleanA paused plan never serves.
refreshes_atstring | nullWhen a plan paused for a spent window refreshes.
statusenumrequiredThe provider-verified key state, written by the hookup check and by real traffic.
provider_errormeans the provider was unreachable when checked, not that the key is bad.scopeenumrequiredowner_user_idstring | nullrequiredrotation_pausedbooleanrequired
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).
404No plan account under this handle.
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 stored sign-in cannot be read; sign in again.
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).
502The provider's usage read or token refresh failed.
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/plans/chatgpt-team/refresh-usage?automatic=false \
-H "Authorization: Bearer YOUR_API_KEY"Response
{
"setup_alias": "chatgpt-team",
"plan": {
"label": "dev@acme.example",
"plan_type": "team",
"primary": {
"used_percent": 12,
"reset_at": "2026-11-19T18:40:00Z",
"window_minutes": 300
},
"secondary": {
"used_percent": 41,
"reset_at": "2026-11-23T09:00:00Z",
"window_minutes": 10080
},
"derived": null,
"checked_at": "2026-11-19T14:21:07.330Z",
"scope": "org",
"owner_user_id": null,
"rotation_paused": false,
"refreshes_at": null
},
"status": "valid",
"scope": "org",
"owner_user_id": null,
"rotation_paused": false
}https://api.experientiallabs.ai/api/orgs/3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10/provider-connections/openai/plans/chatgpt-team/refresh-usage?automatic=false