Plans and limits

Monthly allowances for each plan, how usage is counted, and how to read usage and handle limit errors without retry loops.

Plans

Every plan includes every feature; plans differ only in allowances. Prices are per month in US dollars, plus applicable tax. Compare plans.

Test mode

Test keys have their own allowance on every plan: 10 test accounts, 1,000 simulated publications and 10,000 requests a month. Test usage never counts against live allowances, and test accounts never use a live account slot.

How usage is counted

Usage periods

Paid plans reset every month from the moment the subscription started (UTC). Free, beta, complimentary and test-mode allowances reset at the start of each calendar month (UTC). Unused allowance doesn’t roll over. Every meter reports its reset_at.

Read your usage

Any active key can call GET /usage; no scope is needed. It reports the key’s own mode, test or live, and counts as one API request.

curl https://castrook.com/api/v1/usage \
  -H "Authorization: Bearer $CASTROOK_API_KEY"

{
  "data": {
    "mode": "live",
    "plan": "starter",
    "plan_source": "subscription",
    "catalog_version": "2026-09",
    "period": {
      "start": "2026-10-03T14:20:00.000Z",
      "end": "2026-11-03T14:20:00.000Z"
    },
    "reset_at": "2026-11-03T14:20:00.000Z",
    "grace_ends_at": null,
    "accounts": { "used": 6, "limit": 10, "remaining": 4 },
    "publications": {
      "used": 128,
      "reserved": 12,
      "limit": 300,
      "remaining": 160,
      "reset_at": "2026-11-03T14:20:00.000Z"
    },
    "api_requests": {
      "used": 4210,
      "reserved": 0,
      "limit": 25000,
      "remaining": 20790,
      "reset_at": "2026-11-03T14:20:00.000Z"
    },
    "media_bytes": {
      "used": 5400000000,
      "reserved": 0,
      "limit": 30000000000,
      "remaining": 24600000000,
      "reset_at": "2026-11-03T14:20:00.000Z"
    },
    "comment_requests": {
      "used": 310,
      "reserved": 0,
      "limit": 3000,
      "remaining": 2690,
      "reset_at": "2026-11-03T14:20:00.000Z"
    },
    "new_connections": {
      "used": 2,
      "reserved": 0,
      "limit": 20,
      "remaining": 18,
      "reset_at": "2026-11-03T14:20:00.000Z"
    },
    "rate_limit": { "per_minute": 60 },
    "concurrent_ingests": 2
  }
}

Each meter has used (consumed this period), reserved (held for accepted work that hasn’t finished), limit, remaining (the limit minus used and reserved, never below zero) and reset_at.

Rate limits

Every API response includes the rate-limit headers for the key’s workspace and mode, or for your dashboard session.

Limit errors

A limit error means nothing was accepted and nothing was charged. Handle it once; never retry it in a loop.

{
  "error": {
    "code": "usage_limit_exceeded",
    "message": "This workspace has used its 300 live publications for this period. It resets at 2026-11-03T14:20:00.000Z. Upgrade the plan for a larger allowance.",
    "details": {
      "metric": "publications",
      "mode": "live",
      "plan": "starter",
      "limit": 300,
      "used": 296,
      "reserved": 4,
      "remaining": 0,
      "reset_at": "2026-11-03T14:20:00.000Z",
      "upgrade_url": "https://castrook.com/dashboard/billing",
      "retry_after_seconds": 432000
    }
  },
  "request_id": "req_example"
}

Don’t retry usage_limit_exceeded before reset_at. For a larger allowance, upgrade from Billing in the dashboard; upgrade_url links there. The TypeScript SDK never retries these errors.

try {
  await castrook.posts.create(payload, { idempotencyKey: 'campaign-42-post-7' });
} catch (error) {
  if (error instanceof CastrookError && error.isUsageLimit()) {
    // Nothing was accepted or charged. Try again after the reset.
    console.warn(error.details.metric, 'resets at', error.details.reset_at);
  } else {
    throw error;
  }
}

What keeps working at a limit

• Work that was already accepted keeps its reservation and is delivered.
• When the publication, media or new-connection allowance is used up, other requests keep working, including status reads, cancellations and disconnects.
• When the API request allowance is used up, API keys are rejected until the reset. The dashboard keeps working, because dashboard activity never counts.
• Billing is always available, so you can upgrade at once.

Plan changes and capacity

Upgrades apply immediately. Downgrades take effect at the next renewal. If a downgrade, a cancellation or the end of beta access leaves more connected accounts than the plan allows, nothing is disconnected or deleted: new live posts fail with account_capacity_exceeded until you disconnect accounts or upgrade. Scheduled posts are checked again before delivery, and a destination that is over capacity or out of allowance fails with the matching error and releases its reservation.