# Get confidence scores

`POST https://api.chat-data.com/api/v2/get-confidence-score`

Canonical: https://www.chat-data.com/api-reference/get-confidence-score

## Authentication

Send an API key as a Bearer token: `Authorization: Bearer $CHAT_DATA_API_KEY`. Workspace keys reach every chatbot in the workspace; chatbot-scoped keys reach only their chatbot. Keep keys on the server.

## Description

This operation retrieves the confidence scores (defined as cosine similarity) of the related chunks used to generate answers. You can use it to obtain confidence scores before calling the `/chat` API endpoint, providing an estimate of the chatbot's ability to deliver high-quality answers based on the context. Chunks are cached based on the `messages` array, so subsequent calls to the `/chat` API with the same `messages` array will incur minimal latency in retrieving related vector embeddings from the database. Therefore, calling this API endpoint before `/chat` should not significantly impact overall chat performance.

## Request body (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| messages | array of object | yes | The messages of the conversation, oldest first. On this endpoint, non-image `files` are not downloaded or parsed (only a provided `content` is used), and extra files are not dropped. |
| messages[].role | string | yes | The role of the message sender (`user` or `assistant`). |
| messages[].content | string | yes | The text content of the message. |
| messages[].files | array of object | no | An optional array of file objects attached to the message. Only the chatbot's allowed number of files is kept on the last message (3 by default); extra files are dropped. |
| messages[].files[].name | string | yes | The name of the attached file. |
| messages[].files[].type | string | yes | The MIME type of the file, for example `image/png` or `application/pdf`. Images (`image/*`) are passed to the model as images. Other files are downloaded and parsed to text by the type the file host reports; PDF, DOCX, HTML, plain text and CSV are supported. |
| messages[].files[].url | string | yes | The publicly accessible URL where the file is hosted by you. |
| messages[].files[].content | string | no | The text content of a non-image file. If this field is non-empty, it is used directly without downloading or parsing the file. If it is empty, the file is downloaded and parsed to text when the file type is supported. Files larger than the chatbot's file size limit (3 MB by default) cannot be downloaded, so parse them yourself and provide their content in this field. |
| baseModel | string | no | Overrides the chatbot's `baseModel` setting when processing the RAG context for this request. One of: `gpt-4o-mini`, `gpt-4o`, `gpt-4`, `gpt-4.1-nano`, `gpt-4.1-mini`, `gpt-4.1`, `gpt-5-nano`, `gpt-5-mini`, `gpt-5`, `gpt-5.1`, `gpt-5.2`, `gpt-5.6-sol`, `gpt-5.6-terra`, `gpt-5.6-luna`, `gpt-6-astra`, `gpt-6.1-sol`, `gpt-6-luna`, `gpt-5.5`, `gpt-5.4`, `gpt-5.4-nano`, `gpt-5.4-mini`, `gpt-o1`, `gpt-o3-mini`, `gpt-o3`, `gpt-o4-mini`, `claude-4-5-sonnet`, `claude-4-6-sonnet`, `claude-4-5-haiku`, `claude-4-opus`, `claude-4.1-opus`, `claude-4.5-opus`, `claude-4.6-opus`, `claude-5-opus`, `claude-5-sonnet`, `claude-5-5-opus`, `claude-5-5-sonnet`, `claude-5-5-haiku`, `gemini-3.0-flash`, `gemini-3.1-flash`, `gemini-3.5-flash-lite`, `gemini-3.7-flash`, `gemini-2.5-pro`, `gemini-3.0-pro`, `gemini-3.1-pro`, `deepseek-r1`, `deepseek-v3.2`, `mancer-deepseek-v4-flash`. |
| chatbotId | string | yes | The ID of the chatbot. |

## Example request

```bash
curl 'https://api.chat-data.com/api/v2/get-confidence-score' \
  -H "Authorization: Bearer $CHAT_DATA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "messages": [
    {
      "role": "assistant",
      "content": "How can I help you?"
    },
    {
      "role": "user",
      "content": "How does Chat Data work?"
    }
  ],
  "chatbotId": "6650f1c2a9e4b83d2c7a1f05"
}'
```

## Example response (200)

```json
{
  "status": "success",
  "averageScore": 0.8,
  "scoresArray": [
    0.85,
    0.75
  ],
  "sources": [
    {
      "score": 0.85,
      "url": "https://www.chat-data.com/",
      "title": "Chat Data | Build AI chatbots with your own data",
      "text": "Chat Data lets you build an AI chatbot trained on your own documents, websites and Q&As, then embed it on your site or connect it to WhatsApp, Slack, Discord and more.",
      "type": "website"
    },
    {
      "score": 0.75,
      "question": "How do I train my chatbot?",
      "answer": "Add documents, website links, plain text or Q&As as sources, then retrain the chatbot. Training usually finishes in 1-2 minutes.",
      "type": "q&a"
    }
  ],
  "embeddingText": "How does Chat Data work?"
}
```

## Responses

| Status | Description |
| --- | --- |
| 200 | Successful response. |
| 400 | The scores could not be computed. For example: `chatbotId` is missing, `baseModel` is not an allowed value, `messages` is not an array, is empty, ends with an empty message, or its last message is too long. |
| 401 | Authentication failed: the `Authorization` header is missing or not in the `Bearer <key>` format, the API key does not exist, its workspace is unavailable or has no owner, or the workspace's plan does not include API access. `message` says which. |
| 403 | The API key cannot access the requested chatbot. A chatbot-scoped key used with another chatbot's ID gets `Access denied to this chatbot`. A workspace key gets `Chatbot <id> was not found in this API key's workspace. It may have been deleted or moved to another workspace.` when the chatbot does not exist or belongs to another workspace. |
| 429 | The workspace sent more than 600 API requests in the last minute. Wait the number of seconds given in the `Retry-After` header (and in `message`) before retrying. |