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: 2optional

Sampling temperature.

Example: 0.8

mcp_serversobject[]optional

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

routerobjectoptional

Router configuration for model selection or customization.

extraobjectoptional

Additional configuration options for the completion request.

Responses

application/json

objectoptional

Represents a chat completion response returned by model, based on the provided input.

post

HTTPcURLJavaScriptPython

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: 599

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

OK

{
  "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
    }
  }
}

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 · enumoptional

The format to return the embeddings in.

Default: floatAvailable options:

dimensionsinteger · min: 1 · max: 1536optional

The number of dimensions the resulting embeddings should have.

Example: 1536

Responses

application/json

objectoptional

post

HTTPcURLJavaScriptPython

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
}

A single text input, returning float arrayMultiple text strings, returning base64-encoded vectors

200

Successful response with embeddings

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

Retrieve a list of threads

post

Authorizations

Header parameters

X-Project-Idstringrequired

LangDB project ID

Body

limitinteger · min: 1requiredExample: 10

offsetintegerrequiredExample: 100

Responses

application/json

objectoptional

post

HTTPcURLJavaScriptPython

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
}

200

A list of threads with pagination info

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "created_at": "2025-04-16T07:37:12.492Z",
      "updated_at": "2025-04-16T07:37:12.492Z",
      "model_name": "text",
      "project_id": "text",
      "score": 1,
      "title": "text",
      "user_id": "text"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 100,
    "total": 10
  }
}

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

object[]optional

get

HTTPcURLJavaScriptPython

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: */*

200

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"
  }
]

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

objectoptional

get

HTTPcURLJavaScriptPython

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: */*

200

The total cost and token usage for the specified thread

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

Fetch analytics data

post

Authorizations

Header parameters

X-Project-Idstringrequired

LangDB project ID

Body

start_time_usinteger · int64optional

Start time in microseconds.

Example: 1693062345678

end_time_usinteger · int64optional

End time in microseconds.

Example: 1693082345678

Responses

application/json

objectoptional

post

HTTPcURLJavaScriptPython

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: 59

{
  "start_time_us": 1693062345678,
  "end_time_us": 1693082345678
}

200

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_us": 1,
  "end_time_us": 1
}

Fetch analytics summary

post

Authorizations

Header parameters

X-Project-Idstringrequired

LangDB project ID

Body

start_time_usinteger · int64optionalExample: 1693062345678

end_time_usinteger · int64optionalExample: 1693082345678

groupBystring[]requiredExample: ["provider"]

Responses

application/json

objectoptional

post

HTTPcURLJavaScriptPython

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: 82

{
  "start_time_us": 1693062345678,
  "end_time_us": 1693082345678,
  "groupBy": [
    "provider"
  ]
}

200

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_us": 1,
  "end_time_us": 1
}

Get total usage

post

Authorizations

Header parameters

X-Project-Idstringrequired

LangDB project ID

Body

start_time_usinteger · int64optionalExample: 1693062345678

end_time_usinteger · int64optional

Responses

application/json

objectoptional

post

HTTPcURLJavaScriptPython

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: 47

{
  "start_time_us": 1693062345678,
  "end_time_us": 1
}

200

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": 1737504000000000,
  "period_end": 1740120949421000
}

Retrieve pricing information

get

Returns the pricing details for LangDB services.

Responses

application/json

objectoptional

get

HTTPcURLJavaScriptPython

GET /pricing HTTP/1.1
Host: api.us-east-1.langdb.ai
Accept: */*

200

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
  }
}

List models

get

Responses

application/json

objectoptional

get

HTTPcURLJavaScriptPython

GET /models HTTP/1.1
Host: api.us-east-1.langdb.ai
Accept: */*

200

OK

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