Sync budget accumulators - Pylva

The SDK uses this endpoint to reconcile local budget accumulators with backend totals. Most teams should not call it directly.

Authentication

Send your API key in X-Pylva-Key. Up to 500 entries per request; rate limit is shared with the other telemetry endpoints (1000 requests/min per key).

curl -X POST https://api.pylva.com/api/v1/budget/sync \
  -H "X-Pylva-Key: $PYLVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entries":[{"rule_id":"00000000-0000-0000-0000-000000000000","scope":"per_customer","customer_id":"cust_abc123","accumulated_cost_usd":42.5,"period_start":"2026-06-01T00:00:00.000Z","event_count":18}]}'

Request

{
  "entries": [
    {
      "rule_id": "00000000-0000-0000-0000-000000000000",
      "scope": "per_customer",
      "customer_id": "cust_abc123",
      "accumulated_cost_usd": 42.5,
      "period_start": "2026-06-01T00:00:00.000Z",
      "event_count": 18
    }
  ]
}

Response

{
  "entries": [
    {
      "rule_id": "00000000-0000-0000-0000-000000000000",
      "scope": "per_customer",
      "customer_id": "cust_abc123",
      "period_start": "2026-06-01T00:00:00.000Z",
      "server_total_usd": 43.1,
      "budget_remaining_usd": 56.9,
      "budget_exceeded": false,
      "reconciled_at": "2026-06-11T10:00:00.000Z"
    }
  ]
}

Notes

Backend totals are authoritative.
The SDK overwrites local accumulators from the response.
This endpoint is part of budget hard-stop safety across multiple SDK replicas.