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_01EXAMPLE00000000000000001",
  "customer_id": "con_test_01EXAMPLE00000000000000001",
  "meter_slug": "prd_test_01EXAMPLE00000000000000001",
  "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_01EXAMPLE00000000000000001",
  "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_01EXAMPLE00000000000000001",
  "meter_id": "prd_test_01EXAMPLE00000000000000001",
  "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_01EXAMPLE00000000000000001"

​
customer_id
string
required

The customer ID that made this request

Example:

"con_test_01EXAMPLE00000000000000001"

​
meter_slug
string
required

Slug identifier for the meter configuration used for this request

Example:

"prd_test_01EXAMPLE00000000000000001"

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

​
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'), explicitly provided by the customer ('unmanaged'), or resolved from the customer's stored credentials ('stored')

Available options:
managed,
unmanaged,
stored
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_01EXAMPLE00000000000000001"

​
meter_id
string

Identifier for the meter configuration used for this request

Example:

"prd_test_01EXAMPLE00000000000000001"

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