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.

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.

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

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