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_01KK2NQPKFYW7WKC75P9VVRPRC",
  "connection_id": "con_test_01KK2NQPKG07AXVJC63ATHV497",
  "meter_slug": "prd_test_01KK2NQPKHT4JSVAM65NSBTH50",
  "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_01KK2NQPK3W1JYT9JVDMZDEN8K",
  "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",
    "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_01KK2NQPK5AQ5YREGXAKGCR9XD",
  "meter_id": "prd_test_01KK2NQPK6CZA1PAEF60AJ8WP0",
  "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_01KK2NQPKFYW7WKC75P9VVRPRC"

​
connection_id
string
required

The connection ID that made this request

Example:

"con_test_01KK2NQPKG07AXVJC63ATHV497"

​
meter_slug
string
required

Slug identifier for the meter configuration used for this request

Example:

"prd_test_01KK2NQPKHT4JSVAM65NSBTH50"

​
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_01KK2NQPK3W1JYT9JVDMZDEN8K"

​
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_01KK2NQPK5AQ5YREGXAKGCR9XD"

​
meter_id
string

Identifier for the meter configuration used for this request

Example:

"prd_test_01KK2NQPK6CZA1PAEF60AJ8WP0"

​
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"