Skip to main content
POST
Ingest AI calls

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

AI calls payload.

Required array length: 1 - 2000 elements
​
id
string
required

Caller-generated record id. A record with the same id is deduplicated on storage.

Required string length: 1 - 128
Example:

"aic_01JT4E2Q4N8N0F0X4S2M3R7YQK"

​
run_id
string
required

The run this record belongs to. Every record captured inside one hyperline.run() shares it.

Required string length: 1 - 128
Example:

"run_01JT4E2Q4N8N0F0X4S2M3R7YQL"

​
parent_run_id
string | null
required

The enclosing run, when this one was opened inside another. Null at the top of a run tree.

Required string length: 1 - 128
Example:

null

​
customer_id
string
required

The customer this usage is attributed to — the external id your application knows them by, or a Hyperline cus_… id.

Required string length: 1 - 255
Example:

"cus_xyz789"

​
agent
string
required

Stable agent identity, e.g. the agent's name or type.

Required string length: 1 - 128
Example:

"invoice-copilot"

​
action
string | null
required

What the run does, e.g. deep_research. Null when unnamed.

Required string length: 1 - 128
Example:

"monitoring_analysis"

​
provider
string
required

The model's provider, or the vendor on a cost record.

Required string length: 1 - 64
Example:

"anthropic"

​
model
string
required

The model invoked, or the item purchased on a cost record.

Required string length: 1 - 128
Example:

"claude-sonnet-5"

​
input_tokens
integer
required

Uncached input tokens.

Required range: 0 <= x <= 1000000000
Example:

12400

​
output_tokens
integer
required

Output tokens.

Required range: 0 <= x <= 1000000000
Example:

1300

​
cached_input_tokens
integer
required

Input tokens served from the provider's prompt cache.

Required range: 0 <= x <= 1000000000
Example:

9000

​
cache_write_tokens
integer
required

Input tokens written into the provider's prompt cache.

Required range: 0 <= x <= 1000000000
Example:

0

​
reasoning_tokens
integer
required

Reasoning tokens, on models that bill them separately.

Required range: 0 <= x <= 1000000000
Example:

0

​
status
enum<string>
required

Whether the call succeeded.

Available options:
ok,
error
Example:

"ok"

​
duration_ms
integer
required

Wall-clock duration of the call.

Required range: x >= 0
Example:

1840

​
started_at
string<date-time>
required

When the call started, as an ISO instant.

Example:

"2026-08-18T10:22:31.201Z"

​
metadata
object | null
required

Free-form bag carried alongside the record. At most 50 keys, string values at most 1024 characters, 4096 bytes once serialized.

Example:
​
record_kind
enum<string>
default:llm_call

What the record is. llm_call is a model invocation and the token counters mean something; cost is a non-LLM cost item whose quantity rides in usage_extra. Absent means llm_call, so an older SDK keeps ingesting unchanged.

Available options:
llm_call,
cost
Example:

"llm_call"

​
usage_extra
object | null

Cost dimensions beyond the token classes — provider extras (web searches, image generations) or the caller's own units (vector queries, gpu_seconds). Keys must match [a-z0-9_.]{1,64}, values must be finite and at most 1e12, at most 20 keys.

Example:

Response

202 - application/json

Calls accepted.

​
calls_accepted
integer
required

Number of calls accepted for asynchronous processing.

Example:

42