Log external service token usage

post

https://api.agent700.ai/api/billing/external-usage

Records token usage from an external service (e.g., voice transcription) into the
agent700 billing pipeline. The usage is persisted to the database and reported
to Stripe metered billing — identical to the standard agent chat billing flow.

Authorization

Requires a valid Bearer token (JWT or App Password) for a user who holds the
superadmin role in at least one active organization membership.

Authorization: Bearer <your_access_token>

This endpoint is intended for internal/service-to-service use only. The caller
must be assigned the superadmin role via the organization roles system before
calling this endpoint.

Billing Pipeline

Validates the service_name against the services table.
Validates the model_name against the text_model_costs pricing table.
Calculates serviceCost and agent700Cost from token counts and per-token rates.
Writes a row to user_billable_request_logs (linked to the service, not an agent).
Reports agent700Cost to Stripe metered billing for the specified organization.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Token usage details for the external service call to be billed.
Either service_name (for external services) or an agent context must be
resolvable — this endpoint always uses service_name.

Request body for logging token usage from an external service.

user_id

uuid

required

UUID of the user to whom the usage should be attributed.

organization_id

uuid

required

UUID of the organization used for Stripe metered billing reporting.

model_name

string

required

Name of the LLM model used. Must match an entry in the text_model_costs
pricing table (e.g. gpt-4o-mini, claude-3-5-sonnet-20241022).

prompt_tokens

integer

required

≥ 0

Number of input (prompt) tokens consumed by the model call.

completion_tokens

integer

required

≥ 0

Number of output (completion) tokens produced by the model call.

service_name

string

required

Name of the external service generating this usage. Must match the name
column in the services table (e.g. transcription).

request_channel

string

Defaults to external_api

Optional label identifying the source channel. Defaults to external_api
when omitted.

Responses

Language

Credentials

Bearer

JWT

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

201Usage logged and Stripe billing updated successfully

400Validation error — missing/invalid fields or unknown model

401No valid authentication token provided

403Authenticated user does not have the superadmin role

404Specified user or service not found