A server sender counts its requests per minute and posts one fragment per minute here, so codesafe reads error counts as rates against real traffic.
Request
POST /api/v1/ingest/rollup
X-Codesafe-Key: <api_key>
Content-Type: application/json
The body is one fragment: the counters of one finished minute from one process or pool, at most 16 KB. Several pools on one host each send their own, and codesafe adds them up.
Example
curl
curl -X POST https://codesafe.example/api/v1/ingest/rollup \
-H "X-Codesafe-Key: $CODESAFE_KEY" \
-H "Content-Type: application/json" \
-d "{\"minute\": $(( $(date +%s) / 60 - 1 )), \"instance\": \"web-1\", \"seq\": 1,
\"requests\": 120, \"status\": {\"200\": 117, \"404\": 3}}"JSON
{
"minute": 29889360,
"host": "web-03",
"instance": "fpm-2",
"seq": 88214,
"requests": 18432,
"status": {"200": 17801, "404": 187, "500": 11},
"methods": {"GET": 17994, "POST": 421},
"routes": {"/product/{slug}": 6104, "__unmatched": 187},
"authed": {"yes": 2210, "no": 16222},
"clients": 3421,
"durations": {
"__total": [17000, 1400, 20, 8, 3, 1, 0, 0, 0, 0, 0, 0],
"/product/{slug}": [6000, 100, 4, 0, 0, 0, 0, 0, 0, 0, 0, 0]
},
"durations_fine": {
"__total": [9800, 5100, 2100]
}
}Fields
| Field | Type | Required | Limit | What it does |
|---|---|---|---|---|
minute | integer | yes | within 90 minutes of codesafe's clock | The minute counted: epoch seconds divided by 60, rounded down |
instance | string | yes | [A-Za-z0-9._-]{1,64} | The process or pool that counted |
host | string | no | [A-Za-z0-9._-]{1,64} | The server; tells two servers' pools apart |
seq | integer | yes | ≥ 0 | The fragment's number, rising per instance; makes a retry count once |
requests | integer | yes | 0–100,000,000 | Every request that finished in the minute |
status | object | no | keys 100–599 | Requests per HTTP status |
methods | object | no | GET POST PUT PATCH DELETE HEAD OPTIONS | Requests per method |
routes | object | no | route patterns, ≤ 200 chars | Requests per matched route; __unmatched when none matched |
authed | object | no | yes, no | Requests by a signed-in user, and the rest |
clients | integer | no | 0–100,000,000 | Distinct client addresses in the minute |
durations | object | no | 12 counts per key | Request times per route; __total required when present |
durations_fine | object | no | 3 counts per key | Bucket 0 of durations split at 5, 10 and 25 ms |
shield_observe, shield_block … | object | no | rule ids | The Shield's counters, sent by the official clients |
Every counter is a JSON integer from 0 to 100,000,000; a zero is ignored. codesafe keeps what one minute of the site can count: clients at most requests, and no counter past 120 times the project's usual minute for that hour of day (never under 1,000). A counter past it is clipped and said in ACTIVITY; the fragment still answers 202.
Responses
| Status | When | What the client does |
|---|---|---|
202 | Taken: {"success": true, "accepted": 1, "duplicate": false}; a replay answers accepted: 0, duplicate: true | Nothing |
400 | Malformed JSON, or a fragment codesafe refuses; error names the rule | Fix the sender; never retry |
401 | X-Codesafe-Key is missing, or no active project holds it | Fix the key |
403 | The project takes no rollups | Switch them on, or stop sending |
405 | The method is not POST | Fix the sender |
413 | The fragment is over 16 KB | Fold more routes into __other |
429 | The project's budget is spent; Retry-After: 60 | Retry once after it |
503 | codesafe cannot store it at the moment | Retry once later; the retry counts once |
Notes
- A project takes rollups while accept per-minute traffic rollups is on (DATA tab), the default for a new project. Off, a fragment answers
403and writes nothing. - A route is the matched pattern,
/product/{slug}, never the URI. A key with?or%refuses the whole fragment. - Any broken rule refuses the whole fragment with
400; the message names the rule, never the value. - Rollups have no browser endpoint: a page sees one request, not the stream.
- Nothing in a fragment may come from a request's content: no URI, no address, no user.
Duration buckets
The 12 counts in each durations vector are requests that took at most 25, 50, 100, 200, 400, 800, 1600, 3200, 6400, 12800 and 30000 ms, and the last one counts everything slower. Measure server time, from the request's start to its end. durations_fine splits bucket 0 into at most 5, 10 and 25 ms; a split that does not add up to bucket 0 is ignored for that key alone.
Routes past 40
A fragment keeps its 40 busiest routes; the rest are added into __other, counts and durations alike. __unmatched and __other never count against the 40.
How retries count once
codesafe remembers each fragment by host, instance, minute and seq for 26 hours. The same fragment again answers duplicate: true and adds nothing; a seq that starts over in a later minute still counts.
Reading it back
STATS → PERFORMANCE shows request times per route and the trend, and error rates per 10,000 requests appear in the release comparison. The MCP tool get_traffic answers the same counters for an agent.