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

# Analytics Metadata Ingestion

<Badge icon="arrow-left" color="gray">[Back to API List](/ai-for-service/apis/searchai/api-list)</Badge>

The Ingest Analytics Metadata API allows you to send analytics metadata for search requests processed outside the  Search AI answer generation pipeline. Use this API to report generated answers, answer generation latency, citations, chunk usage, and user feedback so that externally generated answers are reflected in the Answer Analytics dashboard.

<Note> Existing Feedback API integrations continue to work without modification. This API extends analytics capabilities by allowing additional metadata to be associated with a search request.</Note>

| Field             | Value                                                               |
| ----------------- | ------------------------------------------------------------------- |
| **Method**        | POST                                                                |
| **Endpoint**      | `<host_url>/api/public/bot/:appId/search/ingest-analytics-metadata` |
| **Content-Type**  | `application/json`                                                  |
| **Authorization** | `auth: <JWT Token>`                                                 |
| **API Scope**     | `Feedback for Search AI`                                            |

## Request Parameters

| Field                 | Type             | Required | Description                                                                                                                                    |
| --------------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `searchRequestId`     | string           | Yes      | Unique search request identifier returned by the Search API. This value associates the analytics metadata with the originating search request. |
| `feedbackLevel`       | string           | No       | Specifies the feedback category.                                                                                                               |
| `event`               | string           | No       | Specifies the feedback event. Supported values are `thumbsUp` and `thumbsDown`.                                                                |
| `comments`            | object           | No       | Additional feedback information. Currently supports the `tags` field.                                                                          |
| `aiAnswer`            | string           | No       | AI-generated answer associated with the search request. Specify an empty string (`""`) if no answer could be generated.                        |
| `chunksSentToLlm`     | array of strings | No       | List of chunk IDs that were provided as context to the LLM during answer generation.                                                           |
| `chunksUsedForAnswer` | array of strings | No       | List of chunk IDs that contributed to the generated answer.                                                                                    |
| `citationClicks`      | array of objects | No       | Citation interactions performed by the user. Each object contains the chunk identifier and citation position.                                  |
| `llmResponseTime`     | integer          | No       | Time taken by the LLM to generate the answer, in milliseconds.                                                                                 |

## Sample Request

```json theme={null}
curl --location 'https://host/api/public/bot/<appId>/search/ingest-analytics-metadata' \
--header 'auth: eyJhbGciOiJIUzI1NixxxxxxxxxxxXVCJ9.eyJhxxxxxxxxxFlNTM4LWIyNWYtNWYwNC1hZTlmLWE2MzQwNjE0MjhhMSJ9.ByBx2W0Qkpk5mOr3dGZKlZ7Dd8-bxxl0M4xTT63Glu8' \
--header 'Content-Type: application/json;charset=UTF-8' \
--data '{
    "searchRequestId": "fsh-b3737519-3e18-518d-86f8-9da4c36235fd",
    "feedbackLevel": "smartAnswer",
    "event": "thumbsDown",
    "comments": { "tags": ["Wrong Answer", "Hallucination"] },
    "aiAnswer": "To reset your password, go to Settings under Security.",
    "chunksSentToLlm": ["chk-123", "chk-456", "chk-789"],
    "chunksUsedForAnswer": ["chk-123", "chk-456"],
    "llmResponseTime": 2000 
}'
```

## Points to Note

* The `searchRequestId` must correspond to a valid search request generated by the Advance Search V2 API.
* Only `searchRequestId` is mandatory. You can submit any subset of the supported analytics fields. Only the fields which are sent in the request are updated and other fields remain the same.
* You can invoke the API multiple times for the same searchRequestId as additional analytics data becomes available. When multiple requests are submitted for the same searchRequestId, Search AI updates the metadata as follows:
  * The following fields **overwrite** any previously stored values:
    * `comments`
    * `event`
    * `ai_answer`
    * `llm_response_time`
    * `chunks_sent_to_llm`
    * `Chunks_used_for_answer`
  * Data for the following field is appended.
    * `citation_clicks`
* This API is intended for analytics and reporting only. It does not modify search results or answer generation behavior.