API Reference
API Endpoints for LangDB
LangDB project ID
ID of the model to use. This can be either a specific model ID or a virtual model identifier.
gpt-4oSampling temperature.
0.8Nucleus sampling probability.
The maximum number of tokens that can be generated in the chat completion.
How many chat completion choices to generate for each input message.
1Up to 4 sequences where the API will stop generating further tokens.
Penalize new tokens based on whether they appear in the text so far.
Penalize new tokens based on their existing frequency in the text so far.
Whether to return log probabilities of the output tokens.
The number of most likely tokens to return at each position, for which the log probabilities are returned. Requires logprobs=true.
If specified, the backend will make a best effort to return deterministic results.
Format for the model's response.
Controls which (if any) tool is called by the model. none means the model will not call any tool and instead generates a message. auto means the model can pick between generating a message or calling one or more tools. required means the model must call one or more tools.
Whether to enable parallel function calling during tool use.
trueWhether to stream back partial progress.
falseDeprecated. This field is being replaced by safety_identifier and prompt_cache_key.
Use prompt_cache_key to maintain caching optimizations. A stable identifier for your end-users
was previously used to boost cache hit rates by better bucketing similar requests and to help detect and prevent abuse.
Stable identifier for your end-users, used to help detect and prevent abuse. Prefer this over user.
For caching optimization, combine with prompt_cache_key.
Used to cache responses for similar requests to optimize cache hit rates. LangDB supports prompt caching; see https://docs.langdb.ai/features/prompt-caching. Can be used instead of the user field for cache bucketing.
OK
POST /v1/chat/completions HTTP/1.1
Host: api.us-east-1.langdb.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-Project-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 995
{
"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": [
{
"server_url": "wss://your-mcp-server.com/ws?config=your_encoded_config",
"type": "ws"
}
],
"router": {
"routes": [
{
"name": "premium_users",
"conditions": {
"all": [
{
"extra.user.tier": {
"$eq": "premium"
}
}
]
},
"targets": {
"$any": [
"openai/gpt-4o",
"anthropic/claude-3-opus"
],
"sort_by": "ttft",
"sort_order": "min"
}
},
{
"name": "coding_requests",
"conditions": {
"any": [
{
"extra.user.tags": {
"$in": [
"coding",
"development"
]
}
},
{
"messages.0.content": {
"$in": [
"code",
"programming"
]
}
}
]
},
"targets": {
"$any": [
"openai/gpt-4o",
"anthropic/claude-3-5-sonnet"
],
"filter": {
"performance": "high"
},
"sort_by": "price",
"sort_order": "min"
}
}
]
},
"extra": {
"guards": [
"word_count_validator_bd4bdnun",
"toxicity_detection_4yj4cdvu"
],
"user": {
"id": "7",
"name": "mrunmay",
"tags": [
"coding",
"software"
]
}
}
}OK
{
"id": "text",
"choices": [
{
"finish_reason": "stop",
"index": 1,
"message": {
"role": "assistant",
"content": "text",
"tool_calls": [
{
"id": "text",
"type": "function",
"function": {
"name": "text",
"arguments": "text"
}
}
],
"function_call": {
"name": "text",
"arguments": "text"
}
},
"logprobs": {
"content": [
{
"token": "text",
"logprob": 1
}
],
"refusal": [
{
"token": "text",
"logprob": 1
}
]
}
}
],
"created": 1,
"model": "text",
"system_fingerprint": "text",
"object": "chat.completion",
"usage": {
"prompt_tokens": 1,
"completion_tokens": 1,
"total_tokens": 1,
"prompt_tokens_details": {
"cached_tokens": 1,
"cache_creation_tokens": 1,
"audio_tokens": 1
},
"completion_tokens_details": {
"reasoning_tokens": 1,
"accepted_prediction_tokens": 1,
"rejected_prediction_tokens": 1,
"audio_tokens": 1
},
"cost": 1
}
}Creates an embedding vector representing the input text or token arrays.
ID of the model to use for generating embeddings.
text-embedding-ada-002The text to embed.
Array of text strings to embed.
The format to return the embeddings in.
floatPossible values: The number of dimensions the resulting embeddings should have.
1536Successful response with embeddings
POST /v1/embeddings HTTP/1.1
Host: api.us-east-1.langdb.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 136
{
"input": "The food was delicious and the waiter was kind.",
"model": "text-embedding-ada-002",
"encoding_format": "float",
"dimensions": 1536
}Successful response with embeddings
{
"data": [
{
"embedding": [
1
],
"index": 1
}
],
"model": "text",
"usage": {
"prompt_tokens": 1,
"total_tokens": 1
}
}LangDB project ID
10100A list of threads with pagination info
POST /threads HTTP/1.1
Host: api.us-east-1.langdb.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-Project-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 25
{
"limit": 10,
"offset": 100
}A list of threads with pagination info
{
"data": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"created_at": "2025-08-19T23:38:05.940Z",
"updated_at": "2025-08-19T23:38:05.940Z",
"model_name": "text",
"project_id": "text",
"score": 1,
"title": "text",
"user_id": "text"
}
],
"pagination": {
"limit": 10,
"offset": 100,
"total": 10
}
}The ID of the thread to retrieve messages from
LangDB project ID
A list of messages for the given thread
GET /threads/{thread_id}/messages HTTP/1.1
Host: api.us-east-1.langdb.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-Project-Id: text
Accept: */*
A list of messages for the given thread
[
{
"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"
}
]The ID of the thread for which to retrieve cost information
LangDB project ID
The total cost and token usage for the specified thread
GET /threads/{thread_id}/cost HTTP/1.1
Host: api.us-east-1.langdb.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-Project-Id: text
Accept: */*
The total cost and token usage for the specified thread
{
"total_cost": 0.022226999999999997,
"total_output_tokens": 171,
"total_input_tokens": 6725
}LangDB project ID
Start time in microseconds.
1693062345678End time in microseconds.
1693082345678Time period for filtering data. If provided, start_time and end_time will be ignored.
last_monthPossible values: Successful response
POST /analytics HTTP/1.1
Host: api.us-east-1.langdb.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-Project-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 23
{
"period": "last_month"
}Successful response
{
"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": 1,
"end_time": 1
}LangDB project ID
16930623456781693082345678Time period for filtering data. If provided, start_time and end_time will be ignored.
last_monthPossible values: ["provider"]Successful response
POST /analytics/summary HTTP/1.1
Host: api.us-east-1.langdb.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-Project-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 46
{
"period": "last_month",
"groupBy": [
"provider"
]
}Successful response
{
"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": 1,
"end_time": 1
}LangDB project ID
1693062345678End time in microseconds.
1693082345678Time period for filtering data. If provided, start_time and end_time will be ignored.
last_monthPossible values: OK
POST /usage/total HTTP/1.1
Host: api.us-east-1.langdb.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-Project-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 23
{
"period": "last_month"
}OK
{
"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": 1737504000,
"period_end": 1740120949
}LangDB project ID
1693062345678The granularity of the returned usage data.
hourPossible values: Successful response
POST /usage/models HTTP/1.1
Host: api.us-east-1.langdb.ai
Authorization: Bearer YOUR_SECRET_TOKEN
X-Project-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 65
{
"start_time_us": 1693062345678,
"end_time_us": 1,
"min_unit": "hour"
}Successful response
{
"models": [
{
"hour": "2025-02-15 09:00:00",
"provider": "openai",
"model_name": "gpt-4o",
"total_input_tokens": 451235,
"total_output_tokens": 2553,
"total_cost": 1.3843410000000005
}
],
"period_start": 1737504000000000,
"period_end": 1740121147931000
}Returns the pricing details for LangDB services.
Successful retrieval of pricing information
GET /pricing HTTP/1.1
Host: api.us-east-1.langdb.ai
Accept: */*
Successful retrieval of pricing information
{
"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
}
}Register and configure a new LLM under your LangDB project
LangDB Admin Key
my-modelA custom completions model for text and image inputse2e9129b-6661-4eeb-80a2-0c86964974c955f4a12b-74c8-4294-8e4b-537f13fc3861falseopenai-compatiblecompletions0.000010.00003128000["tools"]["text","image"]["text","image"]openai0my-model-v1.2Additional configuration parameters
{"top_k":{"default":0,"description":"Limits the token sampling to only the top K tokens.","min":0,"required":false,"step":1,"type":"int"},"top_p":{"default":1,"description":"Nucleus sampling alternative.","max":1,"min":0,"required":false,"step":0.05,"type":"float"}}Created
POST /admin/models HTTP/1.1
Host: api.xxx.langdb.ai
Authorization: Bearer JWT
X-Admin-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 884
{
"model_name": "my-model",
"description": "A custom completions model for text and image inputs",
"provider_info_id": "e2e9129b-6661-4eeb-80a2-0c86964974c9",
"project_id": "55f4a12b-74c8-4294-8e4b-537f13fc3861",
"public": false,
"request_response_mapping": "openai-compatible",
"model_type": "completions",
"input_token_price": 0.00001,
"output_token_price": 0.00003,
"context_size": 128000,
"capabilities": [
"tools"
],
"input_types": [
"text",
"image"
],
"output_types": [
"text",
"image"
],
"tags": [],
"type_prices": {
"text_generation": 0.00002
},
"mp_price": null,
"owner_name": "openai",
"priority": 0,
"model_name_in_provider": "my-model-v1.2",
"parameters": {
"top_k": {
"default": 0,
"description": "Limits the token sampling to only the top K tokens.",
"min": 0,
"required": false,
"step": 1,
"type": "int"
},
"top_p": {
"default": 1,
"description": "Nucleus sampling alternative.",
"max": 1,
"min": 0,
"required": false,
"step": 0.05,
"type": "float"
}
}
}Created
{
"id": "55f4a12b-74c8-4294-8e4b-537f13fc3861",
"model_name": "my-model",
"description": "A custom completions model for text and image inputs",
"provider_info_id": "e2e9129b-6661-4eeb-80a2-0c86964974c9",
"model_type": "completions",
"input_token_price": "0.00001",
"output_token_price": "0.00003",
"context_size": 128000,
"capabilities": [
"tools"
],
"input_types": [
"text",
"image"
],
"output_types": [
"text",
"image"
],
"tags": [],
"type_prices": null,
"mp_price": null,
"model_name_in_provider": "my-model-v1.2",
"owner_name": "openai",
"priority": 0,
"parameters": {
"top_k": {
"default": 0,
"description": "Limits the token sampling to only the top K tokens.",
"min": 0,
"required": false,
"step": 1,
"type": "int"
},
"top_p": {
"default": 1,
"description": "An alternative to sampling with temperature.",
"max": 1,
"min": 0,
"required": false,
"step": 0.05,
"type": "float"
}
}
}Last updated
Was this helpful?