Skip to content

API traffic records and account health

Preloop records /api/v1 requests, whatever credential they carried (login session, account API key, run-scoped runtime key or CI identity) and whatever status they returned. Health probes (/api/v1/health*), the public billing routes (/api/v1/billing/plans*, /api/v1/billing/create-checkout-session*, /api/v1/billing/webhooks*) and /api/v1/ai-models/providers/* are not recorded. Platform operators can read one account's failures and anomalies over a time window from these records.

What is recorded

Table Content Retention
api_traffic_rollup Request count, total and maximum duration per UTC minute, account, principal kind, method, route template and status class (2xx to 5xx). API_TRAFFIC_ROLLUP_RETENTION_DAYS, default 90
api_traffic_event One row per 4xx or 5xx response, and per list response that came back empty right after a create in its scope. It holds the principal kind and id, route template, status, duration and, where the handler set one, a short reason code. API_TRAFFIC_EVENT_RETENTION_DAYS, default 30, never less than 7

Only route templates such as /api/v1/flows/{flow_id} are stored, never the raw path, query values, headers or bodies. Requests that match no route are stored as <unmatched>.

The recording is outside the restricted CI middleware, so CI requests that the middleware rejects are counted too. Writes happen in memory on the request path and are flushed every API_TRAFFIC_FLUSH_SECONDS (default 10) in one batch. Memory is bounded. If the database is unavailable, the data is kept for the next flush within that bound, and anything over the bound is counted as dropped. API_USAGE_LOGGING_ENABLED=false turns the recording off together with the older per-request usage rows.

Expected volume

A client that polls one route 27 times a minute produces at most one rollup row per minute for that series: 1,440 rows a day instead of 38,880 request rows, or at most 43,200 rows in 30 days instead of about a million. Each additional combination of principal kind, method, route and status class adds at most one row per minute while it is active. Errors add one row each.

Account health

GET /api/v1/operator/accounts/{account_id}/health?since=&until= and preloop accounts health <account-id> [--since 24h] [--json] return, for one account and a window of at most 31 days (default 24 hours):

  • failed flow executions per failure category, with the first execution of each;
  • successful executions with zero tool calls, and with zero model requests (a model request is any gateway call linked to the execution, failed or not; older runs may undercount native tool activity);
  • API routes that answered 4xx or 5xx at least twice, and the individual error responses grouped by status, principal kind and reason code;
  • list responses that came back empty right after a create in the same scope;
  • gateway upstream errors (network and upstream_* classes) per provider and error class. Client cancels, budget and hosted-credit gating are not counted as upstream errors.

Only categories, counts, ids, route templates and first-party codes are returned, never prompts, outputs, raw error text or provider error bodies. Access is limited to installation superusers. Keys bound to a flow execution, runtime session or managed agent are refused even when their owner is a superuser, and restricted CI keys never reach the route.

Run-scoped key maintenance

Flow executions and runtime sessions mint their own API keys. The normal end-of-run paths revoke them, but a run that ended some other way (a crash or a recovery sweep, for example) can leave its key active after it expires. A maintenance pass deactivates active keys that are bound in their context_data to a flow execution or runtime session that has ended, or that have expired. It never touches keys that a person created, which carry neither binding, or durable managed-agent credentials. Key names are never used as evidence. A key keeps working for the post-run flush: the pass skips executions that ended less than five minutes ago and runtime sessions that ended less than an hour ago.

The pass runs hourly as the deactivate_ended_run_keys task. To run it by hand:

python -m preloop.services.run_key_maintenance                 # dry run: counts only
python -m preloop.services.run_key_maintenance --apply         # deactivate
python -m preloop.services.run_key_maintenance --account-id <uuid> --batch-size 500 --max-batches 20

Each applied batch writes one run_keys_deactivated audit row per account with the key ids and the counts per reason (expired, execution_ended, session_ended). The output prints counts only.

Flow delete refusals

A refused DELETE /api/v1/flows/{id} sends an X-Preloop-Delete-Blocker header (built_in_preset on the 403 for a built-in preset; active_executions, references or reference_race on a 409) and writes a flow_delete_refused audit row whose details.reason_code holds the same code, with ids and counts but no names. The traffic event for the 409 holds the code too.