TrueUpp

Usage webhook API

Send line-level usage to TrueUpp as JSON with a bearer token, validated like the line-level CSV and batched into one import per hour.

On this page

Create a token in Settings › Connections, then send up to 10,000 rows per request. Rows use the same fields as the line-level usage CSV and are batched into one import per hour.

Request

POST /api/usage/webhook
Authorization: Bearer tu_ingest_…
Content-Type: application/json

{ "rows": [
  { "account_id": "2077", "metric_name": "api_requests", "usage_at": "2026-07-14T09:31:02Z",
    "quantity": 1, "event_id": "evt_8f2c", "status": "ok" }
] }

From a terminal

# change: set TRUEUPP_URL to your TrueUpp address and TRUEUPP_TOKEN to your token
curl -X POST "$TRUEUPP_URL/api/usage/webhook" \
  -H "Authorization: Bearer $TRUEUPP_TOKEN" -H "Content-Type: application/json" \
  -d '{"rows":[{"account_id":"2077","metric_name":"api_requests","usage_at":"2026-07-14T09:31:02Z","quantity":1,"event_id":"evt_8f2c","status":"ok"}]}'

The token

The token is shown once when you create it; store it in your secrets manager. Revoke it in Settings › Connections if it leaks.

Responses and limits

  • 202 with accepted and deduplicated counts. Rows with an event id already seen are dropped, so retries are safe.
  • 422 if any row is invalid: nothing is imported, and each bad row is listed by index.
  • 400 if the body isn't JSON or has no rows array, and 413 for more than 10,000 rows in one request.
  • 401 for a missing or revoked token, 429 above 120 requests a minute.