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_01KKM3W4FS0Y06EN801TQRSDER",
  "customer_id": "con_test_01KKM3W4FSHRS4799F10MZKT0F",
  "meter_slug": "prd_test_01KKM3W4FSZR10HBDPG4BZSB58",
  "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_01KKM3W4FRS8CQGG957KDQ5V5P",
  "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"
  },
  "cost": "0.0581000000",
  "charge": {
    "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"
      }
    ]
  },
  "metadata": {
    "key": "user_id",
    "value": "123456"
  },
  "created_at": "2023-05-15T14:22:31Z",
  "customer_id": "con_test_01KKM3W4FR05VV70ZMQRFQH7PV",
  "meter_id": "prd_test_01KKM3W4FRDW120WKX8QPY1RY3",
  "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_01KKM3W4FS0Y06EN801TQRSDER"

​
customer_id
string
required

The customer ID that made this request

Example:

"con_test_01KKM3W4FSHRS4799F10MZKT0F"

​
meter_slug
string
required

Slug identifier for the meter configuration used for this request

Example:

"prd_test_01KKM3W4FSZR10HBDPG4BZSB58"

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

​
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
​
cost
string
required

Base AI provider cost for this request in USD (high precision decimal as string)

Example:

"0.0581000000"

​
charge
object
required
​
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"

​
customer_id
string

Identifier for the customer that made this request

Example:

"con_test_01KKM3W4FR05VV70ZMQRFQH7PV"

​
meter_id
string

Identifier for the meter configuration used for this request

Example:

"prd_test_01KKM3W4FRDW120WKX8QPY1RY3"

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