Skip to main content
POST
/
requests
Create request
curl --request POST \
  --url https://api.lava.so/v1/requests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "request_id": "req_test_01KJHF4SFNQP84BSRH9SKK8JFW",
  "connection_id": "con_test_01KJHF4SFPHQ9Q3YE4WKHWCXWG",
  "meter_slug": "prd_test_01KJHF4SFQFDW3FSTNKVB00N6E",
  "metadata": {
    "user_id": "123456",
    "session_id": "abc123"
  },
  "input_tokens": 845,
  "output_tokens": 412,
  "input_characters": 5000,
  "output_characters": 2500,
  "input_seconds": 2,
  "output_seconds": 5
}
'
{ "request_id": "req_test_01KJHF4SFDVBMHJDVAP71KP4QH", "status": "pending", "provider": "openai", "endpoint": "POST https://api.openai.com/v1/chat/completions", "provider_key_type": "managed", "model_usage": { "input_tokens": 845, "output_tokens": 412, "total_tokens": 1257, "input_characters": 0, "output_characters": 0, "total_characters": 0, "input_seconds": 0, "output_seconds": 0, "total_seconds": 0, "input_cost": "0.0169000000", "output_cost": "0.0412000000", "total_cost": "0.0581000000", "payer": "wallet" }, "fee": { "amount": "0.0058100000", "rate_type": "percentage", "token_basis": "input+output", "breakdown": [ { "tier": { "start": 0, "rate": "0.0000000000", "type": "tokens_1m" }, "tokens": 1000000, "characters": 0, "seconds": 0, "cost": "0.0000000000" } ] }, "service_charge": { "amount": "0.0058100000", "payer": "wallet" }, "total_request_cost": "0.0639100000", "total_wallet_cost": "0.0639100000", "total_merchant_cost": "0.0000000000", "metadata": { "key": "user_id", "value": "123456" }, "created_at": "2023-05-15T14:22:31Z", "connection_id": "con_test_01KJHF4SFG5MTHC9PRWS3PZ66C", "meter_id": "prd_test_01KJHF4SFGYD4ZX31FBKG5FGZV", "model": "gpt-4", "response_id": "chatcmpl-abc123def456ghi789", "timestamp": "2023-05-15T14:22:31Z" }

Authorizations

​
Authorization
string
header
required

Bearer token authentication used for standard API calls. Format: 'Bearer YOUR_API_KEY'

Body

application/json
​
request_id
string
required

Unique identifier for the AI API request

Example:

"req_test_01KJHF4SFNQP84BSRH9SKK8JFW"

​
connection_id
string
required

The connection ID that made this request

Example:

"con_test_01KJHF4SFPHQ9Q3YE4WKHWCXWG"

​
meter_slug
string
required

Slug identifier for the meter configuration used for this request

Example:

"prd_test_01KJHF4SFQFDW3FSTNKVB00N6E"

​
metadata
object

Optional metadata to associate with the request. Must be a JSON object with up to 100 key-value pairs, where both keys and values are strings between 1-255 characters. Keys must contain only ASCII letters, numbers, and underscores (no spaces or special characters).

Example:
{
  "user_id": "123456",
  "session_id": "abc123"
}
​
input_tokens
integer

Number of input/prompt tokens used in the request

Required range: x >= 0
Example:

845

​
output_tokens
integer

Number of output/completion tokens generated in the response

Required range: x >= 0
Example:

412

​
input_characters
integer

Number of input characters used in the request

Required range: x >= 0
Example:

5000

​
output_characters
integer

Number of output characters generated in the response

Required range: x >= 0
Example:

2500

​
input_seconds
number

Number of seconds spent processing the input

Required range: x >= 0
Example:

2

​
output_seconds
number

Number of seconds spent generating the output

Required range: x >= 0
Example:

5

Response

Request created or retrieved

​
request_id
string
required

Unique identifier for the AI API request

Example:

"req_test_01KJHF4SFDVBMHJDVAP71KP4QH"

​
status
enum<string>
required

Status of the request: 'pending' (request was created but not yet completed), 'completed' (request was completed and metered successfully), 'error' (request failed to be metered)

Available options:
pending,
completed,
error
Example:

"pending"

​
provider
string
required

Provider used for the request (e.g., openai, anthropic, deepseek, mistral, xai, google)

Example:

"openai"

​
endpoint
string
required

Full endpoint path used for the forwarded request

Example:

"POST https://api.openai.com/v1/chat/completions"

​
provider_key_type
enum<string>
required

Indicates whether the provider key used for this request was managed by Lava ('managed') or provided by the customer ('unmanaged')

Available options:
managed,
unmanaged
Example:

"managed"

​
model_usage
object
required
​
fee
object
required
​
service_charge
object
required
​
total_request_cost
string
required

Total cost of the request including fees and service charges (high precision decimal as string)

Example:

"0.0639100000"

​
total_wallet_cost
string
required

Total cost of the request charged to the wallet (high precision decimal as string)

Example:

"0.0639100000"

​
total_merchant_cost
string
required

Total cost of the request charged to the you, the merchant (high precision decimal as string)

Example:

"0.0000000000"

​
metadata
object
required

Metadata associated with the request, key-value pairs that can be used to help track the request in your system. Keys must contain only ASCII letters, numbers, and underscores (no spaces or special characters).

​
created_at
string<date-time>
required

ISO 8601 timestamp when the request was created and initially recorded by Lava

Example:

"2023-05-15T14:22:31Z"

​
connection_id
string

Identifier for the connection that made this request

Example:

"con_test_01KJHF4SFG5MTHC9PRWS3PZ66C"

​
meter_id
string

Identifier for the meter configuration used for this request

Example:

"prd_test_01KJHF4SFGYD4ZX31FBKG5FGZV"

​
model
string

AI model used for the request (e.g., gpt-4, claude-3-opus)

Example:

"gpt-4"

​
response_id
string

Original response ID returned from the AI provider

Example:

"chatcmpl-abc123def456ghi789"

​
timestamp
string<date-time>

ISO 8601 request completion timestamp returned by the provider

Example:

"2023-05-15T14:22:31Z"