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 boostPct, boostExpiresAt, offPeak, touSavedPct, relief, demo, and infraState keys arrive in every successful response. null inside the relief block carries a meaning of its own — it is not an absence of data.

The limitReset key may be absent entirely — check for its presence: the block arrives when limit reset with a promotion right is enabled for the account. No key means no capability.

Response example

{
  "portal": {
    "id": "d41f0b93-6c85-42e7-9a13-58bd0e7c2f46",
    "domain": "mycompany.bitrix24.com"
  },
  "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 }
  },
  "completion": { "phase": "normal", "resetAt": "2026-06-09T17:30:00.000Z" },
  "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",
  "boostPct": 0,
  "boostExpiresAt": null,
  "offPeak": {
    "enabled": true,
    "visible": "now",
    "timezone": "UTC",
    "currentMultiplier": 0.5,
    "currentWindowEndsInHours": 6,
    "nextAtOrBelow": { "inHours": 1, "multiplier": 0.5 },
    "perModel": false,
    "modelName": null,
    "grid": [
      [0.75, 0.87, 0.87, 0.87, 0.87, 0.87, 0.87, 0.87, 0.75, 0.75, 0.75, 0.75, 0.62, 0.5, 0.75, 0.87, 1, 1, 0.87, 0.87, 0.87, 0.75, 0.75, 0.75],
      [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.62, 0.62, 0.62, 0.62, 0.75, 0.75, 0.87, 0.87, 0.75, 0.75, 0.75, 0.75, 0.62, 0.5, 0.5],
      [0.5, 0.5, 0.62, 0.62, 0.75, 0.62, 0.62, 0.62, 0.75, 0.75, 0.87, 1, 1, 0.87, 0.75, 0.87, 0.87, 0.75, 0.75, 0.62, 0.62, 0.62, 0.62, 0.62],
      [0.75, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.62, 0.62, 0.62, 0.75, 0.75, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0.87],
      [1, 1, 1, 1, 1, 0.87, 0.87, 0.87, 0.87, 1, 1, 1, 1, 1, 1, 0.87, 0.75, 0.75, 0.75, 0.87, 1, 1, 1, 1],
      [1, 1, 1, 1, 1, 0.87, 0.87, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0.87, 0.87, 0.75, 0.87],
      [0.75, 0.62, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.62, 0.75, 0.75, 0.62, 0.62, 0.75, 0.75, 0.87, 0.87, 1, 1, 1, 1, 0.87]
    ],
    "nowCell": { "dow": 1, "hour": 3 }
  },
  "touSavedPct": 12.4,
  "activation": {
    "model": "tariff",
    "tariffInfoUrl": "https://www.bitrix24.com/prices/",
    "marketTrial": {
      "available": false,
      "unavailableReason": "region_not_supported",
      "status": "not_attempted",
      "endsAt": null,
      "activatedAt": null
    }
  },
  "relief": {
    "resetGrantedAt": "2026-06-09T12:00:00.000Z",
    "boostGrantedAt": null
  },
  "demo": null,
  "demoOffer": null,
  "infraState": {
    "frozen": false,
    "reason": null,
    "topupUrl": 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 and the tariffInfoUrl key is absent entirely. For such an account marketTrial.available can be true. It comes back false with reason not_required_for_data once the platform no longer treats the Marketplace path as a precondition for reading company data with this key — there is no need to offer the trial in that case. The account type makes no difference here: cloud and self-hosted answer the same way.

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 counted per account and key owner, so all of one person's devices share it; the recommended interval stays well inside it, and above it the endpoint answers 429 RATE_LIMITED.

PARKED means the seat has no active owner. A paid seat moves to this state when its owner is no longer an active member of the Bitrix24 account while the paid term is still running. Nothing is charged for such a seat, and it keeps its tier and paid term. A Bitrix24 account administrator can hand it over to another employee. Within a day after the paid term ends, the seat moves to PAUSED.

The activation block may be absent from the response entirely — a platform that does not know about it yet responds this way. This is a normal state: if the block is missing, keep working 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 general 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) — your UI must handle a missing 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.

The limitReset block holds the data for the limit reset button. The Cowork/Code app spends the right: the desktop key picks the first usable right (seatAlreadyReset: false); when there is none, do not show the button. The block value matches what the subscription summary returns.

See also

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

Choose Demo before activation

When an offer is available, the Cowork/Code app shows its demoOffer terms and sends the user's choice with the desktop key.