> ## Documentation Index
> Fetch the complete documentation index at: https://lava.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create request

> Create a new API request with usage tracking and billing. This endpoint allows you to manually create requests that were made outside of the forward endpoint.



## OpenAPI

````yaml /openapi.json post /requests
openapi: 3.0.0
info:
  title: Lava API
  description: >-
    Lava API enables businesses to implement usage-based billing for AI
    services. This API allows tracking, managing, and billing for third-party AI
    API usage through a forwarding system.
  version: 1.0.0
  contact:
    name: Lava support
    url: https://www.lava.so/contact
servers:
  - url: https://api.lava.so/v1/
    description: Lava API v1
security: []
tags:
  - name: Authentication
  - name: Core Endpoints
  - name: Models
  - name: Services
  - name: Requests
  - name: Wallet
  - name: Payment Methods
  - name: Spend Keys
  - name: Usage
  - name: Checkout Sessions
  - name: Customers
  - name: Plans
  - name: Subscriptions
  - name: Meters
  - name: Webhooks
  - name: Secret Keys
  - name: Credit Bundles
  - name: Gateway Settings
  - name: Skills
  - name: News Data
  - name: Search
  - name: Enrich
paths:
  /requests:
    post:
      tags:
        - Requests
      summary: Create request
      description: >-
        Create a new API request with usage tracking and billing. This endpoint
        allows you to manually create requests that were made outside of the
        forward endpoint.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - request_id
                - customer_id
                - meter_slug
              properties:
                request_id:
                  type: string
                  example: req_test_01EXAMPLE00000000000000001
                  description: Unique identifier for the AI API request
                customer_id:
                  type: string
                  description: The customer ID that made this request
                  example: con_test_01EXAMPLE00000000000000001
                meter_slug:
                  type: string
                  description: >-
                    Slug identifier for the meter configuration used for this
                    request
                  example: prd_test_01EXAMPLE00000000000000001
                metadata:
                  type: object
                  description: >-
                    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:
                  type: integer
                  minimum: 0
                  description: Number of input/prompt tokens used in the request
                  example: 845
                output_tokens:
                  type: integer
                  minimum: 0
                  description: Number of output/completion tokens generated in the response
                  example: 412
                input_characters:
                  type: integer
                  minimum: 0
                  description: Number of input characters used in the request
                  example: 5000
                output_characters:
                  type: integer
                  minimum: 0
                  description: Number of output characters generated in the response
                  example: 2500
                input_seconds:
                  type: number
                  minimum: 0
                  description: Number of seconds spent processing the input
                  example: 2
                output_seconds:
                  type: number
                  minimum: 0
                  description: Number of seconds spent generating the output
                  example: 5
      responses:
        '200':
          description: Request created or retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Request'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                body_json_parse_error:
                  summary: Invalid JSON in request body
                  value:
                    error:
                      message: >-
                        Request body contains invalid JSON. Please check your
                        request body syntax and ensure it's properly formatted.
                      code: body_json_parse_error
                      status: 400
                body_schema_validation_failed:
                  summary: Invalid request body schema
                  value:
                    error:
                      message: >-
                        Request body doesn't match the required schema. Please
                        refer to the API documentation for the correct
                        structure.
                      code: body_schema_validation_failed
                      status: 400
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                auth_header_missing:
                  summary: Authorization header missing
                  value:
                    error:
                      message: >-
                        Authorization header is required. Please include an
                        'Authorization' header with your request.
                      code: auth_header_missing
                      status: 401
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                rest_internal_server_error:
                  summary: Internal server error
                  value:
                    error:
                      message: >-
                        An internal server error occurred while processing your
                        request.
                      code: rest_internal_server_error
                      status: 500
      security:
        - Auth: []
components:
  schemas:
    Request:
      type: object
      properties:
        request_id:
          type: string
          example: req_test_01EXAMPLE00000000000000001
          description: Unique identifier for the AI API request
        status:
          type: string
          enum:
            - pending
            - completed
            - error
          example: pending
          description: >-
            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)
        customer_id:
          type: string
          example: con_test_01EXAMPLE00000000000000001
          description: Identifier for the customer that made this request
        meter_id:
          type: string
          example: prd_test_01EXAMPLE00000000000000001
          description: Identifier for the meter configuration used for this request
        provider:
          type: string
          example: openai
          description: >-
            Provider used for the request (e.g., openai, anthropic, deepseek,
            mistral, xai, google)
        model:
          type: string
          example: gpt-4
          description: AI model used for the request (e.g., gpt-4, claude-3-opus)
        endpoint:
          type: string
          example: POST https://api.openai.com/v1/chat/completions
          description: Full endpoint path used for the forwarded request
        provider_key_type:
          type: string
          enum:
            - managed
            - unmanaged
            - stored
          example: managed
          description: >-
            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')
        response_id:
          type: string
          example: chatcmpl-abc123def456ghi789
          description: Original response ID returned from the AI provider
        model_usage:
          type: object
          properties:
            input_tokens:
              type: integer
              example: 845
              description: Number of input/prompt tokens used in the request
            output_tokens:
              type: integer
              example: 412
              description: Number of output/completion tokens generated in the response
            total_tokens:
              type: integer
              example: 1257
              description: Total tokens (input + output) for this request
            input_characters:
              type: integer
              example: 0
              description: Total characters (input) for this request
            output_characters:
              type: integer
              example: 0
              description: Total characters (output) for this request
            total_characters:
              type: integer
              example: 0
              description: Total characters (input + output) for this request
            input_seconds:
              type: integer
              example: 0
              description: Total seconds (input) for this request
            output_seconds:
              type: integer
              example: 0
              description: Total seconds (output) for this request
            total_seconds:
              type: integer
              example: 0
              description: Total seconds (input + output) for this request
            input_cost:
              type: string
              example: '0.0169000000'
              description: Cost of input tokens in USD (high precision decimal as string)
            output_cost:
              type: string
              example: '0.0412000000'
              description: Cost of output tokens in USD (high precision decimal as string)
            total_cost:
              type: string
              example: '0.0581000000'
              description: >-
                Total cost of the request in USD (high precision decimal as
                string)
          required:
            - input_tokens
            - output_tokens
            - total_tokens
            - input_characters
            - output_characters
            - total_characters
            - input_seconds
            - output_seconds
            - total_seconds
            - input_cost
            - output_cost
            - total_cost
        cost:
          type: string
          example: '0.0581000000'
          description: >-
            Base AI provider cost for this request in USD (high precision
            decimal as string)
        charge:
          type: object
          properties:
            amount:
              type: string
              example: '0.0058100000'
              description: Fee amount in USD (high precision decimal as string)
            rate_type:
              type: string
              enum:
                - fixed
                - percentage
              example: percentage
              description: >-
                Fee model: 'fixed' (credits per usage unit) or 'percentage'
                (percentage of provider base cost)
            breakdown:
              type: array
              description: >-
                Breakdown of the fee calculation for this request to help with
                understanding how the fee was calculated across tiers
              items:
                type: object
                properties:
                  tier:
                    type: object
                    properties:
                      start:
                        type: integer
                        example: 0
                        description: >-
                          Start of the usage tier in the unit type specified in
                          the tier type
                      rate:
                        type: string
                        example: '0.0000000000'
                        description: >-
                          For fixed rate_type: credits per usage unit (decimal
                          string). For percentage rate_type: percentage of
                          provider base cost (e.g. '120' for 120%).
                      type:
                        type: string
                        enum:
                          - tokens_1m
                          - characters_1m
                          - minutes
                          - requests
                        example: tokens_1m
                        description: >-
                          Unit type of the usage tier: 'tokens_1m' (tokens per
                          1M), 'characters_1m' (characters per 1M), 'minutes'
                          (minutes), or 'requests' (requests)
                    required:
                      - start
                      - rate
                      - type
                  tokens:
                    type: integer
                    example: 1000000
                    description: Number of tokens used in this tier
                  characters:
                    type: integer
                    example: 0
                    description: Number of characters used in this tier
                  seconds:
                    type: integer
                    example: 0
                    description: Number of seconds used in this tier
                  cost:
                    type: string
                    example: '0.0000000000'
                    description: >-
                      Cost of the request for this tier in USD (high precision
                      decimal as string)
                required:
                  - tier
                  - tokens
                  - characters
                  - seconds
                  - cost
          required:
            - amount
            - rate_type
            - breakdown
        metadata:
          type: object
          description: >-
            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).
          properties:
            key:
              type: string
              description: >-
                Key of the metadata (must contain only ASCII letters, numbers,
                and underscores)
              example: user_id
            value:
              type: string
              description: Value of the metadata
              example: '123456'
          required:
            - key
            - value
        timestamp:
          type: string
          format: date-time
          example: '2023-05-15T14:22:31Z'
          description: ISO 8601 request completion timestamp returned by the provider
        created_at:
          type: string
          format: date-time
          example: '2023-05-15T14:22:31Z'
          description: >-
            ISO 8601 timestamp when the request was created and initially
            recorded by Lava
      required:
        - request_id
        - status
        - provider
        - endpoint
        - provider_key_type
        - model_usage
        - cost
        - charge
        - metadata
        - created_at
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Human-readable error message describing what went wrong
              example: Invalid authentication credentials
            code:
              type: string
              description: Machine-readable error code describing what went wrong
              example: forward_token_json_invalid
            status:
              type: integer
              description: HTTP status code of the error
              example: 400
            issues:
              type: array
              items:
                type: object
                properties:
                  path:
                    type: array
                    items:
                      type: string
                    description: Path to the field that caused the validation error
                  message:
                    type: string
                    description: Error message describing the validation issue
                required:
                  - path
                  - message
              description: >-
                Optional array of specific validation issues with their paths
                and messages
              example:
                - path:
                    - model
                  message: 'Missing required field: model'
                - path:
                    - messages
                    - '0'
                    - content
                  message: Invalid message content format
          required:
            - message
            - code
            - status
      required:
        - error
  securitySchemes:
    Auth:
      type: http
      scheme: bearer
      description: >-
        Bearer token authentication used for standard API calls. Format: 'Bearer
        YOUR_API_KEY'

````