SuperAgent API

Per-endpoint limits

Limits stop one key or worker from using more than you intended. For each endpoint you can cap requests per minute, hour, or day, how many run at once, and, for selected money operations, Agent Credits spent per day.

Limits are fixed when the key is created. To change them, create a replacement key.

Set limits on a key

const result = await hive.apiKeys.create(
  {
    label: "Bounded worker",
    scopes: [
      "services:read",
      "services:invoke",
      "wallets:read",
      "wallets:transact",
    ],
    allowedServices: ["hive-research", "managed-wallets"],
    limits: {
      "*": {
        requestsPerHour: 2_000,
        maxConcurrent: 20,
      },
      "services.invoke": {
        requestsPerMinute: 120,
      },
      "services.invoke.hive-research": {
        requestsPerMinute: 30,
        maxConcurrent: 3,
      },
      "services.invoke.hive-research.analyses.create": {
        requestsPerDay: 250,
      },
      "services.invoke.cloud-superbrain.memory.answer": {
        requestsPerMinute: 10,
        requestsPerDay: 500,
      },
      "wallets.transactions.create": {
        requestsPerDay: 10,
        creditsPerDay: 25,
      },
      "credits.x402.topUp": {
        requestsPerDay: 4,
      },
    },
  },
  { idempotencyKey: "bounded-worker-v1" },
);

Limit fields

Field	Meaning	Accepted maximum
`requestsPerMinute`	Requests during a fixed minute window.	60,000
`requestsPerHour`	Requests during a fixed hour window.	1,000,000
`requestsPerDay`	Requests during a fixed UTC day.	10,000,000
`maxConcurrent`	Requests for the selector that may be in progress at once.	1,000
`creditsPerDay`	HivemindOS credits charged by one supported operation during a fixed UTC day.	1,000,000,000

Request and concurrency values must be positive integers. creditsPerDay must be positive with at most three decimal places.
A key may define at most 128 selectors.
The maximums are validation ceilings, not default quotas. An omitted field adds no limit, but account balance, plan allowance, service availability, wallet policy, and ancestor-key limits still apply.
Concurrent capacity stays in use until the response finishes, including a streamed one. Always consume or cancel response bodies.

Limit selectors

The limits object is keyed by operation id:

Selector	Applies to
`*`	Every authenticated SuperAgent API operation.
A static operation such as `databases.actions`	Only that endpoint operation.
`services.invoke`	Every direct managed-service invocation.
`services.invoke.<serviceId>`	Direct invocation of one managed service.
`services.invoke.<serviceId>.<operationId>`	One exact registered capability invoked directly.
`runs.create`	Every durable run creation.
`runs.create.<serviceId>`	Run creation for one managed service.
`runs.create.<serviceId>.<operationId>`	One exact registered capability created as a run.

Every matching selector applies, and the request is rejected as soon as any one is used up. For hive-research operation analyses.create, the API checks *, services.invoke, services.invoke.hive-research, and services.invoke.hive-research.analyses.create. Likewise, services.invoke.cloud-superbrain.memory.answer limits memory answers alone, while services.invoke.cloud-superbrain caps every Cloud Superbrain operation.

The SDK exports every accepted operation id as HIVEMINDOS_PLATFORM_OPERATION_IDS; they are also in the endpoint reference.

Daily credit limits

creditsPerDay works only on operations whose maximum charge can be checked before work starts:

wallets.create
wallets.transactions.create
wallets.signatures.create
trading.orders.create
swaps.execute

It cannot be set on *, a managed-service selector, a quote, a read, or any other operation. Before a paid action starts, the API checks that its maximum charge fits the remaining limit; only the final charge counts toward the daily total.

A key’s credit limit does not add credits and does not replace wallet policy. A request must pass the key limit, have enough account credits, and satisfy the wallet’s own rules.

credits.x402.topUp accepts request and concurrency limits but not creditsPerDay, because it buys credits rather than spending them. The unsigned HTTP 402 challenge does not use up a request slot; the first signed payment attempt does, and an idempotent replay of a completed top-up does not.

Child keys and ancestor limits

Every key above a child still applies its limits. If a root key allows 1,000 requests per hour and its child allows 100, the child gets 100. A child cannot set a covering limit higher than an ancestor’s, and leaving a limit out does not bypass the parent. Revoking or expiring any ancestor invalidates the child.

Use this to set organization-wide ceilings on the root key and smaller budgets on each worker.

Handle HTTP 429

When a key hits a request, concurrency, or daily-credit limit, the API returns HTTP 429:

{
  "ok": false,
  "code": "rate_limit_exceeded",
  "error": "This API key has reached its request limit for this operation.",
  "operationId": "services.invoke.hive-research",
  "metric": "requestsPerMinute",
  "retryAfterSeconds": 18
}

With these headers:

Retry-After: 18
X-HivemindOS-Limit-Operation: services.invoke.hive-research

Pause that workload for at least retryAfterSeconds. Queueing work in your backend is usually better than having every caller retry. Another operation may still have capacity, but do not route around a deliberate key-wide or ancestor limit.

const result = await hive.services.invokeOperation(
  "hive-research",
  "analyses.create",
  { question: "..." },
  { idempotencyKey: jobId },
);

if (!result.ok && result.code === "rate_limit_exceeded") {
  await queueForLater(jobId, result.retryAfterSeconds ?? 60);
}