Analytics Metadata Ingestion

Back to API List 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.

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.

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

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.

​Request Parameters

​Sample Request

​Points to Note

Request Parameters

Sample Request

Points to Note