Cowork/Code subscription state

GET /v1/cowork/state

Returns a full snapshot of the Cowork/Code subscription state: the tier, the subscription state, quota usage across three windows in percent, a recommendation to wait or move to a higher tier, and the tier catalog for a comparison table.

Examples

curl — personal key

curl https://vibecode.bitrix24.com/v1/cowork/state \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

curl https://vibecode.bitrix24.com/v1/cowork/state \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/cowork/state', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

if (!res.ok) {
  const { error } = await res.json()
  console.error(error.code, error.message)
} else {
  const state = await res.json()
  const tight = state.windows[state.bottleneck]
  console.log(`Window ${state.bottleneck}: ${tight.pctUsed}%`, tight.exhausted ? 'exhausted' : 'ok')
}

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/cowork/state', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const state = await res.json()

Response fields

The offPeak and touSavedPct keys arrive only when off-peak hours are enabled for the account. Until then, they are absent from the response body entirely, and the example below does not show them.

The relief key arrives only when quota relief is enabled for the account. Until the capability is on for your platform, it is absent from the response body entirely, and the example below does not show it. Test for the presence of the key, not for its value: null inside the block carries a meaning of its own.

Response example

{
  "subscription": {
    "tier": "FREE",
    "state": "ACTIVE",
    "currentPeriodStart": "2026-06-01T00:00:00.000Z",
    "currentPeriodEnd": "2026-07-01T00:00:00.000Z",
    "nextChargeAt": null,
    "cancelAtPeriodEnd": false,
    "pendingTier": null,
    "termMonths": 1,
    "paidThroughAt": "2026-05-15T00:00:00.000Z"
  },
  "windows": {
    "fiveHour": { "pctUsed": 40, "resetAt": "2026-06-09T17:30:00.000Z", "exhausted": false },
    "week":     { "pctUsed": 24, "resetAt": "2026-06-12T09:00:00.000Z", "exhausted": false },
    "month":    { "pctUsed": 20, "resetAt": "2026-07-01T00:00:00.000Z", "exhausted": false }
  },
  "bottleneck": "fiveHour",
  "recommendation": {
    "reason": "none",
    "triggerWindow": null,
    "wait": null,
    "upgrade": { "available": true, "nextTier": "PRO" }
  },
  "tiers": [
    { "tier": "FREE",  "multiplier": null,  "feeVibes": 0,   "current": true,  "isNext": false },
    { "tier": "PRO",   "multiplier": "×1",  "feeVibes": 20,  "current": false, "isNext": true  },
    { "tier": "MAX",   "multiplier": "×5",  "feeVibes": 100, "current": false, "isNext": false },
    { "tier": "ULTRA", "multiplier": "×20", "feeVibes": 200, "current": false, "isNext": false }
  ],
  "serverTime": "2026-06-09T14:05:00.000Z",
  "activation": {
    "model": "tariff",
    "tariffInfoUrl": "https://www.bitrix24.com/prices/",
    "marketTrial": {
      "available": false,
      "unavailableReason": "region_not_supported",
      "status": "not_attempted",
      "endsAt": null,
      "activatedAt": null
    }
  }
}

The example shows an account on the tariff model, which is how every international account works. Where the subscription model applies, activation.model is subscription, the tariffInfoUrl key is absent entirely, and marketTrial.available can be true.

Error response example

404 — subscription not activated:

{
  "success": false,
  "error": {
    "code": "COWORK_NOT_ACTIVATED",
    "message": "No active Cowork/Code subscription for this user+portal"
  }
}

Errors

The full list of common API errors — Errors.

Known specifics

A successful response (200) is the state object itself, without a success wrapper. Errors arrive in the envelope { success: false, error: { code, message } }. Determine success by the HTTP status (res.ok).

The window-exhaustion flag is the exhausted field, not pctUsed === 100. The pctUsed value is rounded to an integer: 99.6% shows as 100, though the window is not yet exhausted.

Measure the time until reset from serverTime, not from the device clock — clock drift between the client and the server skews the counter.

Windows reset lazily on read — if there have been no requests since the reset time, the reset is applied when you call the endpoint, so the snapshot is always current.

Poll no more than once every 15–30 seconds. The response is not cached (Cache-Control: no-store). The endpoint has a rate limit shared by the account and the key owner, so every device of one person draws on the same budget; the recommended interval stays well inside it, and above it the endpoint answers 429 RATE_LIMITED.

The activation block may be absent from the response entirely — that is the response from a platform that does not know about it yet. This is a normal state: no block means behave as before. When the block is there, available and unavailableReason inside it are always present, so test for the BLOCK and read the VALUE of the field, never the other way round.

activation.marketTrial.available is a forecast, not a guarantee. false is final: do not show the trial step. true means you may offer it, but it does not promise success — the account state can change between the poll and the click, and the final decision stays with Bitrix24, so keep handling a refusal at activation time.

The list of unavailableReason values may grow. Read an unknown value as "do not offer the trial", with no special branch. The same goes for status.

activation.tariffInfoUrl is a shared terms page, not an address specific to your account. The value is constant and may be absent from the response (a subscription-model region, a self-hosted account) — the screen must survive without the link. Do not persist it and do not parse its host.

An empty relief.boostGrantedAt does not mean there is no limit increase. The stamp is there for a one-off notification and stays visible for 7 days, while an increase is granted for up to 30 days. An increase granted more than seven days ago reports an empty stamp and is still in effect. Only boostPct tells you whether an increase is in effect.

The value of the relief block matches what the subscription summary returns. Store the stamp you have already reported to the user once per application, not separately per endpoint, or the same relief will be shown twice. Notify only when a non-empty value differs from the one you stored: the server deliberately turns a stamp into null (the visibility window closed, the increase expired or was revoked, the seat was handed over), so a plain "it changed — show it" rule would fire a false notice on every such transition.

See also

• Cowork/Code subscription summary
• Off-peak hours in the Cowork/Code subscription
• Cowork/Code
• Limits and optimization
• Errors