POST/api/orgs/{org_id}/provider-connections/{provider}/spend-refresh

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

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

  • providerenumrequired

    The provider to connect.

    "openai""anthropic""azure_openai""openrouter""gemini""bedrock""fireworks""modal""vertex""zai""qwen""tencent""meta""cerebras""wafer""huawei""mistral""dashscope""xai""deepseek""typesafe""kenari""kiosapi""tokenharbor""groq""nvidia_nim"

Query parameters

  • setup_aliasstring

    The account handle. Omitted, the provider-named default account.

Responses

  • 200

    The refresh outcome.

    Response
    • providerenumrequired

      A provider an organization can connect its own key for. kenari, kiosapi, tokenharbor, groq and nvidia_nim are free-tier providers open to every plan.

      "openai""anthropic""azure_openai""openrouter""gemini""bedrock""fireworks""modal""vertex""zai""qwen""tencent""meta""cerebras""wafer""huawei""mistral""dashscope""xai""deepseek""typesafe""kenari""kiosapi""tokenharbor""groq""nvidia_nim"
    • kindenumrequired

      not_reportable: the provider exposes no billing to this credential; read_failed: the message names the failure and fix.

      "reported""not_reportable""read_failed"
    • refreshedbooleanrequired

      False when the staleness floor answered from the stored reading.

    • staleness_floor_secondsintegerrequired
    • next_refresh_atstring | nullrequired

      When a fresh query is allowed; null once allowed.

    • messagestringrequired
    • snapshotobject | nullrequired
      One of

      object

      • taken_atstringrequired
      • sourceenumrequired

        provider_api: the provider's billing API; our_side: AWS Cost Explorer.

        "provider_api""our_side""self_reported""ledger_derived"
      • spend_usdnumber | nullrequired

        Spend reported by the provider, in dollars.

      • credits_remaining_usdnumber | nullrequired

        Remaining prepaid balance, in dollars.

      • usage_limit_usdnumber | nullrequired

        Account usage limit, in dollars.

      • detailobject | nullrequired
  • 400

    The request is malformed or names an unsupported value.

    Response
    • errorstringrequired

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

  • 401

    Missing, unknown or revoked API key.

    Response
    • errorstringrequired

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

    Response
    • errorstringrequired

      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

    The resource does not exist or belongs to another organization.

    Response
    • errorstringrequired

      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 account is a plan account, not an API key.

    Response
    • errorstringrequired

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

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