POST/api/orgs/{org_id}/provider-connections/{provider}/plans/{setup_alias}/refresh-usage

Refresh 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.

認証: AuthorizationヘッダーにBearer形式のAPIキー

パスパラメータ

  • org_idstring必須

    Your organization id (uuid). GET /api/whoami returns it.

  • providerenum必須

    openai for ChatGPT plans, anthropic for Claude plans. Any other provider answers 404.

    "openai""anthropic"
  • setup_aliasstring必須

    The plan account handle.

クエリパラメータ

  • automaticboolean

    A live poll; reuses a reading younger than 45 seconds and audits only a verdict change.

    デフォルト: false

レスポンス

  • 200

    The plan account after the read.

    レスポンス
    • setup_aliasstring必須
    • planobject必須

      What a plan account carries instead of a key.

      plan
      • labelstring必須
      • plan_typestring | null必須

        For example plus, pro, team, max.

      • primaryobject | null必須
        いずれか

        object

        • used_percentinteger必須
        • reset_atstring | null必須
        • window_minutesinteger | null必須
      • secondaryobject | null必須
        いずれか

        object

        • used_percentinteger必須
        • reset_atstring | null必須
        • window_minutesinteger | null必須
      • derivedobject | null
        いずれか

        object

        • five_hourobject | null必須
          いずれか

          object

          • requestsinteger必須
          • input_tokensinteger必須
          • cached_input_tokensinteger必須
          • output_tokensinteger必須
          • first_activitystring | null必須
          • last_activitystring | null必須
        • seven_dayobject | null必須
          いずれか

          object

          • requestsinteger必須
          • input_tokensinteger必須
          • cached_input_tokensinteger必須
          • output_tokensinteger必須
          • first_activitystring | null必須
          • last_activitystring | null必須
      • checked_atstring | null必須
      • scopeenum

        org: the shared pool; account: only API keys created by owner_user_id.

        "org""account"
        デフォルト: "org"
      • owner_user_idstring | null
      • rotation_pausedboolean

        A paused plan never serves.

        デフォルト: false
      • refreshes_atstring | null

        When a plan paused for a spent window refreshes.

    • statusenum必須

      The provider-verified key state, written by the hookup check and by real traffic. provider_error means the provider was unreachable when checked, not that the key is bad.

      "unchecked""valid""invalid""rate_limited""quota_exhausted""provider_error"
    • scopeenum必須
      "org""account"
    • owner_user_idstring | null必須
    • rotation_pausedboolean必須
  • 401

    Missing, unknown or revoked API key.

    レスポンス
    • errorstring必須

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 403

    The 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).

    レスポンス
    • errorstring必須

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 404

    No plan account under this handle.

    レスポンス
    • errorstring必須

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 409

    The stored sign-in cannot be read; sign in again.

    レスポンス
    • errorstring必須

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 502

    The provider's usage read or token refresh failed.

    レスポンス
    • errorstring必須

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

リクエスト

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"

レスポンス

{
  "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