API Reference

Create chat completion

post

Authorizations

Header parameters

X-Project-Idstringrequired

LangDB project ID

Body

modelstringrequired

ID of the model to use. This can be either a specific model ID or a virtual model identifier.

Example: gpt-4o

messagesobject[]required

A list of messages in the conversation.

temperaturenumber · max: 2

Sampling temperature.

Example: 0.8

mcp_serversobject[]

Model Context Protocol servers to use during the request. These enable capabilities like web search.

routerobject

Router configuration for model selection or customization.

extraobject

Additional configuration options for the completion request.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.us-east-1.langdb.ai/v1/chat/completions' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'X-Project-Id: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "user",
        "content": "Write a haiku about recursion in programming."
      }
    ],
    "temperature": 0.8,
    "max_tokens": 1000,
    "top_p": 0.9,
    "frequency_penalty": 0.1,
    "presence_penalty": 0.2,
    "stream": false,
    "response_format": "json_object",
    "mcp_servers": [
      {
        "name": "websearch",
        "type": "in-memory"
      }
    ],
    "router": {
      "name": "kg_random_router",
      "type": "script",
      "script": "const route = ({ request, headers, models, metrics }) => { return {model: 'test'};};"
    },
    "extra": {
      "guards": [
        "word_count_validator_bd4bdnun",
        "toxicity_detection_4yj4cdvu"
      ],
      "user": {
        "id": "7",
        "name": "mrunmay",
        "tags": [
          "coding",
          "software"
        ]
      }
    }
  }'

200

200

{
  "id": "text",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 1,
      "message": {
        "role": "assistant",
        "content": "text"
      },
      "logprobs": {
        "content": [
          {
            "token": "text",
            "logprob": 1
          }
        ],
        "refusal": [
          {
            "token": "text",
            "logprob": 1
          }
        ]
      }
    }
  ],
  "created": 1,
  "model": "text",
  "service_tier": "scale",
  "system_fingerprint": "text",
  "object": "chat.completion",
  "usage": {
    "prompt_tokens": 1,
    "completion_tokens": 1,
    "total_tokens": 1,
    "prompt_tokens_details": {
      "cached_tokens": 1
    },
    "completion_tokens_details": {
      "reasoning_tokens": 1,
      "accepted_prediction_tokens": 1,
      "rejected_prediction_tokens": 1
    }
  }
}

OK

Create embeddings

post

Creates an embedding vector representing the input text or token arrays.

Authorizations

Body

modelstringrequired

ID of the model to use for generating embeddings.

Example: text-embedding-ada-002

inputone ofrequired

The text to embed.

Array of text strings to embed.

encoding_formatstring · enum · default: "float"

The format to return the embeddings in.

Options: float, base64

dimensionsinteger · min: 1 · max: 1536

The number of dimensions the resulting embeddings should have.

Example: 1536

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.us-east-1.langdb.ai/v1/embeddings' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "input": "The food was delicious and the waiter was kind.",
    "model": "text-embedding-ada-002",
    "encoding_format": "float",
    "dimensions": 1536
  }'

200

200

{
  "data": [
    {
      "embedding": [
        1
      ],
      "index": 1
    }
  ],
  "model": "text",
  "usage": {
    "prompt_tokens": 1,
    "total_tokens": 1
  }
}

Successful response with embeddings

Retrieve a list of threads

post

Authorizations

Header parameters

X-Project-Idstringrequired

LangDB project ID

Body

limitinteger · min: 1required

Example: 10

offsetintegerrequired

Example: 100

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.us-east-1.langdb.ai/threads' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'X-Project-Id: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "limit": 10,
    "offset": 100
  }'

200

200

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2025-03-20T23:51:11.142Z",
      "updated_at": "2025-03-20T23:51:11.142Z",
      "model_name": "text",
      "project_id": "text",
      "score": 1,
      "title": "text",
      "user_id": "text"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 100,
    "total": 10
  }
}

A list of threads with pagination info

Retrieve messages for a specific thread

get

Authorizations

Path parameters

thread_idstring · uuidrequired

The ID of the thread to retrieve messages from

Header parameters

X-Project-Idstringrequired

LangDB project ID

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.us-east-1.langdb.ai/threads/{thread_id}/messages' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'X-Project-Id: text'

200

200

[
  {
    "model_name": "gpt-4o-mini",
    "thread_id": "123e4567-e89b-12d3-a456-426614174000",
    "user_id": "langdb",
    "content_type": "Text",
    "content": "text",
    "content_array": [
      "text"
    ],
    "type": "system",
    "tool_call_id": "123e4567-e89b-12d3-a456-426614174000",
    "tool_calls": "text",
    "created_at": "2025-01-29 10:25:00.736000",
    "id": "123e4567-e89b-12d3-a456-426614174000"
  }
]

A list of messages for the given thread

Retrieve the total cost for a specific thread

get

Authorizations

Path parameters

thread_idstring · uuidrequired

The ID of the thread for which to retrieve cost information

Header parameters

X-Project-Idstringrequired

LangDB project ID

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.us-east-1.langdb.ai/threads/{thread_id}/cost' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'X-Project-Id: text'

200

200

{
  "total_cost": 0.022226999999999997,
  "total_output_tokens": 171,
  "total_input_tokens": 6725
}

The total cost and token usage for the specified thread

Fetch analytics data

post

Authorizations

Header parameters

X-Project-Idstringrequired

LangDB project ID

Body

start_time_usinteger · int64

Start time in microseconds.

Example: 1693062345678

end_time_usinteger · int64

End time in microseconds.

Example: 1693082345678

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.us-east-1.langdb.ai/analytics' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'X-Project-Id: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "start_time_us": 1693062345678,
    "end_time_us": 1693082345678
  }'

200

200

{
  "timeseries": [
    {
      "hour": "2025-02-20 18:00:00",
      "total_cost": 12.34,
      "total_requests": 1000,
      "avg_duration": 250.5,
      "duration": 245.7,
      "duration_p99": 750.2,
      "duration_p95": 500.1,
      "duration_p90": 400.8,
      "duration_p50": 200.3,
      "total_duration": 1,
      "total_input_tokens": 1,
      "total_output_tokens": 1,
      "error_rate": 1,
      "error_request_count": 1,
      "avg_ttft": 1,
      "ttft": 1,
      "ttft_p99": 1,
      "ttft_p95": 1,
      "ttft_p90": 1,
      "ttft_p50": 1,
      "tps": 1,
      "tps_p99": 1,
      "tps_p95": 1,
      "tps_p90": 1,
      "tps_p50": 1,
      "tpot": 0.85,
      "tpot_p99": 1.5,
      "tpot_p95": 1.2,
      "tpot_p90": 1,
      "tpot_p50": 0.75,
      "tag_tuple": [
        "text"
      ]
    }
  ],
  "start_time_us": 1,
  "end_time_us": 1
}

Successful response

Fetch analytics summary

post

Authorizations

Header parameters

X-Project-Idstringrequired

LangDB project ID

Body

start_time_usinteger · int64

Example: 1693062345678

end_time_usinteger · int64

Example: 1693082345678

groupBystring[]required

Example: ["provider"]

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.us-east-1.langdb.ai/analytics/summary' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'X-Project-Id: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "start_time_us": 1693062345678,
    "end_time_us": 1693082345678,
    "groupBy": [
      "provider"
    ]
  }'

200

200

{
  "summary": [
    {
      "tag_tuple": [
        "openai",
        "gpt-4"
      ],
      "total_cost": 156.78,
      "total_requests": 5000,
      "total_duration": 1250000,
      "avg_duration": 250,
      "duration": 245.5,
      "duration_p99": 750,
      "duration_p95": 500,
      "duration_p90": 400,
      "duration_p50": 200,
      "total_input_tokens": 100000,
      "total_output_tokens": 50000,
      "avg_ttft": 100,
      "ttft": 98.5,
      "ttft_p99": 300,
      "ttft_p95": 200,
      "ttft_p90": 150,
      "ttft_p50": 80,
      "tps": 10.5,
      "tps_p99": 20,
      "tps_p95": 15,
      "tps_p90": 12,
      "tps_p50": 8,
      "tpot": 0.85,
      "tpot_p99": 1.5,
      "tpot_p95": 1.2,
      "tpot_p90": 1,
      "tpot_p50": 0.75,
      "error_rate": 1,
      "error_request_count": 1
    }
  ],
  "start_time_us": 1,
  "end_time_us": 1
}

Successful response

Get total usage

post

Authorizations

Header parameters

X-Project-Idstringrequired

LangDB project ID

Body

start_time_usinteger · int64

Example: 1693062345678

end_time_usinteger · int64

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.us-east-1.langdb.ai/usage/total' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'X-Project-Id: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "start_time_us": 1693062345678,
    "end_time_us": 1
  }'

200

200

{
  "models": [
    {
      "provider": "openai",
      "model_name": "gpt-4o",
      "total_input_tokens": 3196182,
      "total_output_tokens": 74096,
      "total_cost": 10.4776979999,
      "cost_per_input_token": 3,
      "cost_per_output_token": 12
    }
  ],
  "total": {
    "total_input_tokens": 4181386,
    "total_output_tokens": 206547,
    "total_cost": 11.8904386859
  },
  "period_start": 1737504000000000,
  "period_end": 1740120949421000
}

OK

Retrieve pricing information

get

Returns the pricing details for LangDB services.

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.us-east-1.langdb.ai/pricing'

200

200

{
  "model": "gpt-3.5-turbo-0125",
  "provider": "openai",
  "price": {
    "per_input_token": 0.5,
    "per_output_token": 1.5,
    "valid_from": null
  },
  "input_formats": [
    "text"
  ],
  "output_formats": [
    "text"
  ],
  "capabilities": [
    "tools"
  ],
  "type": "completions",
  "limits": {
    "max_context_size": 16385
  }
}

Successful retrieval of pricing information

List models

get

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url 'https://api.us-east-1.langdb.ai/models'

200

200

{
  "object": "list",
  "data": [
    {
      "id": "o1-mini",
      "object": "model",
      "created": 1686935002,
      "owned_by": "openai"
    }
  ]
}

OK