Admin

2 operations

API usage

GET/admin/api-usage

AdminBeta: may change

API traffic over the last days (UTC): totals, the busiest keys, collectors and operations, refusals (429s) and errors, callers blocked right now, and the limits in force (tiers, quotas, block settings). Signed-out callers are counted together; no network addresses are kept.

SDK method: collector.getAdminApiUsage()
Key scopes: admin:ops:read
Headers: X-Request-Id

Query parameters

daysinteger
How many days back (1–90).
1–90 · default 7

Responses

200OKThe summary.

ApiUsageSummary

API traffic for Admin → API usage: totals, the busiest keys, collectors and operations, blocks, and the limits in force.

sincestring (date)required
The first day counted (UTC).
daysintegerrequired
totalsobjectrequired
ShowHide the fields of totals
- requestsintegerrequired
- limitedintegerrequired
- errors4xxintegerrequired
- errors5xxintegerrequired
dailyarray of objectrequired
ShowHide the fields of daily
- daystring (date)required
- requestsintegerrequired
- limitedintegerrequired
  Requests refused by a rate limit (429).
- errorsintegerrequired
  Answers with a 4xx (other than our 429s) or a 5xx.
keysarray of objectrequired
The busiest API keys (top 25).
ShowHide the fields of keys
- subjectstringrequired
- keyIdstring (uuid)required
- namestring or nullrequired
- prefixstring or nullrequired
- kindenum or nullrequired
  One ofpersonalstoreadmin
- ownerobject or nullrequired
  ShowHide the fields of owner
  idstring (uuid)required
  labelstring or nullrequired
- requestsintegerrequired
- limitedintegerrequired
- errors4xxintegerrequired
- errors5xxintegerrequired
- lastDaystring (date)required
usersarray of objectrequired
The busiest signed-in collectors in our apps (top 25).
ShowHide the fields of users
- subjectstringrequired
- userIdstring (uuid)required
- labelstring or nullrequired
- requestsintegerrequired
- limitedintegerrequired
- errors4xxintegerrequired
- errors5xxintegerrequired
- lastDaystring (date)required
anonymousobjectrequired
Signed-out callers, counted together (no network addresses are kept).
ShowHide the fields of anonymous
- requestsintegerrequired
- limitedintegerrequired
routesarray of objectrequired
The busiest operations (top 25).
ShowHide the fields of routes
- routestringrequired
- requestsintegerrequired
- limitedintegerrequired
- errors4xxintegerrequired
- errors5xxintegerrequired
blocksarray of objectrequired
Callers blocked right now.
ShowHide the fields of blocks
- subjectstringrequired
  key:<id>, user:<id> or ip:<address> (a network guessing keys).
- labelstring or nullrequired
- blockedUntilstring (date-time)required
- levelintegerrequired
  How many times in a row: each block doubles.
- reasonstringrequired
- blockedAtstring (date-time)required
tiersarray of objectrequired
ShowHide the fields of tiers
- tierenumrequired
  One ofanonymousappfreepaidstoreadmin
- perMinuteintegerrequired
- perDayinteger or nullrequired
- descriptionstringrequired
quotasarray of objectrequired
ShowHide the fields of quotas
- bucketstringrequired
- perDayintegerrequired
- descriptionstringrequired
settingsobjectrequired
ShowHide the fields of settings
- personalKeysRequirePaidbooleanrequired
- blockThresholdintegerrequired
- blockWindowMinutesintegerrequired
- blockMinutesintegerrequired
- blockMaxMinutesintegerrequired

5Errors400 · 404 · 429 · 500 · 503

400
invalid_request
invalid_request: The query or body doesn’t match the schema (see errors[]).
404
not_found
not_found: Not an admin (moderator): the same 404 as a missing route.
429
rate_limited temporarily_blocked
rate_limited: Over the caller’s limit: the per-minute burst or the per-day quota (RateLimit headers; wait Retry-After seconds).
temporarily_blocked: Too many refused requests in a row: blocked for a while (Retry-After says how long).
500
internal
internal: Something went wrong on our side (quote the requestId).
503
not_available
not_available: Usage isn’t recorded on this server yet.

curl 'https://api.collection.id/v1/admin/api-usage?days=7' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

{
  "since": "2026-10-05",
  "days": 7,
  "totals": {
    "requests": 48210,
    "limited": 37,
    "errors4xx": 812,
    "errors5xx": 4
  },
  "daily": [
    {
      "day": "2026-10-10",
      "requests": 6950,
      "limited": 5,
      "errors": 118
    },
    {
      "day": "2026-10-11",
      "requests": 7124,
      "limited": 9,
      "errors": 121
    }
  ],
  "keys": [
    {
      "subject": "key:0b4f3b1e-6c1a-4f5e-9f0e-1f2a3b4c5d6e",
      "keyId": "0b4f3b1e-6c1a-4f5e-9f0e-1f2a3b4c5d6e",
      "name": "Spreadsheet sync",
      "prefix": "abcd1234",
      "kind": "personal",
      "owner": {
        "id": "6f2c0a4e-3b1d-4c8e-9a7f-2d5e8b1c4a90",
        "label": "A Collector"
      },
      "requests": 1840,
      "limited": 0,
      "errors4xx": 12,
      "errors5xx": 0,
      "lastDay": "2026-10-11"
    }
  ],
  "users": [
    {
      "subject": "user:6f2c0a4e-3b1d-4c8e-9a7f-2d5e8b1c4a90",
      "userId": "6f2c0a4e-3b1d-4c8e-9a7f-2d5e8b1c4a90",
      "label": "A Collector",
      "requests": 3210,
      "limited": 0,
      "errors4xx": 9,
      "errors5xx": 0,
      "lastDay": "2026-10-11"
    }
  ],
  "anonymous": {
    "requests": 20140,
    "limited": 28
  },
  "routes": [
    {
      "route": "GET /api/v1/catalog/search",
      "requests": 15320,
      "limited": 21,
      "errors4xx": 140,
      "errors5xx": 1
    }
  ],
  "blocks": [
    {
      "subject": "ip:198.51.100.23",
      "label": "A network guessing API keys",
      "blockedUntil": "2026-10-11T07:02:11.610Z",
      "level": 1,
      "reason": "More than 50 refused requests in 10 minutes.",
      "blockedAt": "2026-10-11T06:47:11.610Z"
    }
  ],
  "tiers": [
    {
      "tier": "anonymous",
      "perMinute": 60,
      "perDay": 2000,
      "description": "Signed-out callers, per network address."
    },
    {
      "tier": "free",
      "perMinute": 120,
      "perDay": 10000,
      "description": "Personal API keys of collectors on the Free plan, per key."
    }
  ],
  "quotas": [
    {
      "bucket": "bulk",
      "perDay": 200,
      "description": "Bulk and batch writes (imports, bulk edits) per caller per day."
    },
    {
      "bucket": "exports",
      "perDay": 20,
      "description": "Collection exports (CSV/JSON) per caller per day."
    }
  ],
  "settings": {
    "personalKeysRequirePaid": false,
    "blockThreshold": 50,
    "blockWindowMinutes": 10,
    "blockMinutes": 15,
    "blockMaxMinutes": 1440
  }
}

Lift an API block

POST/admin/api-usage/blocks/lift

AdminBeta: may change

Ends a temporary block early (a key, collector or network that kept going after being refused) and clears its count of refusals. Audited.

SDK method: collector.liftAdminApiBlock()
Key scopes: admin:ops:write
Headers: X-Request-Id

Request body required · application/json

LiftApiBlock

subjectstringrequired

Responses

200OKWhether a block was lifted.

LiftedApiBlock

liftedbooleanrequired
false when it wasn’t blocked (any more).

6Errors400 · 404 · 413 · 429 · 500 · 503

400
invalid_request invalid_json
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
404
not_found
not_found: Not an admin (moderator): the same 404 as a missing route.
413
payload_too_large
payload_too_large: The body is over 1,048,576 bytes, this operation’s limit.
429
rate_limited temporarily_blocked
rate_limited: Over the caller’s limit: the per-minute burst or the per-day quota (RateLimit headers; wait Retry-After seconds).
temporarily_blocked: Too many refused requests in a row: blocked for a while (Retry-After says how long).
500
internal
internal: Something went wrong on our side (quote the requestId).
503
not_available
not_available: Usage isn’t recorded on this server yet.

curl -X POST 'https://api.collection.id/v1/admin/api-usage/blocks/lift' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "subject": "ip:198.51.100.23"
  }'

{
  "lifted": true
}

{ "since": "2026-10-05", "days": 7, "totals": { "requests": 48210, "limited": 37, "errors4xx": 812, "errors5xx": 4 }, "daily": [ { "day": "2026-10-10", "requests": 6950, "limited": 5, "errors": 118 }, { "day": "2026-10-11", "requests": 7124, "limited": 9, "errors": 121 } ], "keys": [ { "subject": "key:0b4f3b1e-6c1a-4f5e-9f0e-1f2a3b4c5d6e", "keyId": "0b4f3b1e-6c1a-4f5e-9f0e-1f2a3b4c5d6e", "name": "Spreadsheet sync", "prefix": "abcd1234", "kind": "personal", "owner": { "id": "6f2c0a4e-3b1d-4c8e-9a7f-2d5e8b1c4a90", "label": "A Collector" }, "requests": 1840, "limited": 0, "errors4xx": 12, "errors5xx": 0, "lastDay": "2026-10-11" } ], "users": [ { "subject": "user:6f2c0a4e-3b1d-4c8e-9a7f-2d5e8b1c4a90", "userId": "6f2c0a4e-3b1d-4c8e-9a7f-2d5e8b1c4a90", "label": "A Collector", "requests": 3210, "limited": 0, "errors4xx": 9, "errors5xx": 0, "lastDay": "2026-10-11" } ], "anonymous": { "requests": 20140, "limited": 28 }, "routes": [ { "route": "GET /api/v1/catalog/search", "requests": 15320, "limited": 21, "errors4xx": 140, "errors5xx": 1 } ], "blocks": [ { "subject": "ip:198.51.100.23", "label": "A network guessing API keys", "blockedUntil": "2026-10-11T07:02:11.610Z", "level": 1, "reason": "More than 50 refused requests in 10 minutes.", "blockedAt": "2026-10-11T06:47:11.610Z" } ], "tiers": [ { "tier": "anonymous", "perMinute": 60, "perDay": 2000, "description": "Signed-out callers, per network address." }, { "tier": "free", "perMinute": 120, "perDay": 10000, "description": "Personal API keys of collectors on the Free plan, per key." } ], "quotas": [ { "bucket": "bulk", "perDay": 200, "description": "Bulk and batch writes (imports, bulk edits) per caller per day." }, { "bucket": "exports", "perDay": 20, "description": "Collection exports (CSV/JSON) per caller per day." } ], "settings": { "personalKeysRequirePaid": false, "blockThreshold": 50, "blockWindowMinutes": 10, "blockMinutes": 15, "blockMaxMinutes": 1440 } }