---
title: "Metered pay-per-use call"
method: POST
path: "/wrapped/credits/{provider}/{endpoint}"
tags: ["Burn"]
---

# Metered pay-per-use call

`POST /wrapped/credits/{provider}/{endpoint}`

## Request

- Base URL: `https://api.paywithlocus.com/api`
- URL: `https://api.paywithlocus.com/api/wrapped/credits/{provider}/{endpoint}`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer

The response body is the RAW upstream response (byte-compatible with the provider SDK shape). Cost rides in response headers. `X-Locus-End-User` present (or an end-user token or end-user-bound Agent Connection) charges that user's account at your effective price; a secret-key call without it or a platform-mode Agent Connection charges your platform account at base price with zero markup.

## Path parameters

- `provider` string, required
- `endpoint` string, required

## Headers

- `X-Locus-Max-Charge-Credits` string
- `X-Locus-Session-Id` string
- `Idempotency-Key` string, required
- `Prefer` string
- `X-Locus-End-User` string: Case-sensitive immutable ID in the tenant namespace. Prefer an identity-provider subject, not an email address.

## Request body

- object: Upstream-shaped request body (see the per-endpoint docs at /credits/md)

## Response `200`

Raw upstream response. For fal/generate this acknowledges queue submission: credits remain reserved until a background reconciler confirms the result. Confirmed failures release the hold; successful results capture it. Read /wrapped/credits/calls/{callId} for settlement status.

## Other responses

- `202`: Prefer: respond-async was applied. The provider request is out and the call finishes in the background. A same-key retry while it runs answers 202 again. Headers: Preference-Applied, Location (statusUrl), Retry-After, X-Locus-Api-Call-Id.
- `400`: Missing Idempotency-Key, locally invalid request, or caller-correctable upstream validation error
- `402`: Insufficient credits
- `403`: The call was refused before dispatch and no credits moved. Either the endpoint is disabled for this tenant or outside the credential's scope, or the workspace has reached its monthly spend limit — the latter carries code TENANT_MONTHLY_SPEND_LIMIT_EXCEEDED and is terminal until resetsAt.
- `409`: Idempotency-Key reused with a different body, or charge_ceiling_exceeded before any reservation or provider dispatch
- `422`: Caller-correctable upstream validation error; credits are released
- `503`: Provider gateway failure: Locus sends a provider 502 or 504 as 503 so the edge passes the JSON error body (code, upstreamStatus, apiCallId, and providerError.code when the provider sent one) through; X-Locus-Origin-Status carries the original status and credits are released. Also fal_queue_receipt_persistence_pending: submission was dispatched but neither receipt copy could be persisted. Credits remain held. Retry with the same Idempotency-Key or read statusUrl; do not create a new job. An unrecoverable receipt releases its hold after 24 hours and reports UNCONFIRMED.

---

[API](https://skmtc.dev/paywithlocus/apis/locus-pro-api.md) - [All operations](https://skmtc.dev/paywithlocus/apis/locus-pro-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paywithlocus/apis/locus-pro-api/revisions/aab8fa5d6cef?raw)