Tracking API (REST)

The Tracking API (REST) sends analytics events to the tracking ingestion endpoint.

Endpoint

• Method: GET or POST
• Endpoint pattern: https://<analytics-host>/api/v2/track/

UI Navigation

Find this endpoint and tracking key in Site Search > App Settings > All APIs > Analytics.

Authentication Model

This endpoint validates event keys in payload content, not Authorization token headers.

• Required payload field: properties.key
• Transport field: data (Base64-encoded JSON event payload)
• Optional payload fields: properties.language (language code; both dash and underscore language-code variants are accepted and normalized automatically) and properties.model (search profile name for profile-level analytics)

Request Parameters

Note: Both dash and underscore language-code variants are accepted and normalized automatically, so use the language code your integration sends.

Request Examples

Build the Base64-encoded event JSON in data. Include language and model in the decoded payload when you want language-scoped analytics and profile-level analytics reporting.

Note: Include model to populate profile-level analytics dashboards.

Sample request (GET):

curl -sS --get \
  --data-urlencode "data=<base64-encoded-event-json>" \
  "https://<analytics-host>/api/v2/track/"

Sample request (POST):

curl -sS -X POST \
  --data-urlencode "data=<base64-encoded-event-json>" \
  "https://<analytics-host>/api/v2/track/"

Event Types

Use the event identifiers below in the decoded JSON payload. Each event includes shared required fields: top-level event, plus properties.key and any event-specific required fields listed for that event type.

_search

What it tracks: A user search request and result impressions shown on the search page.

When to send it: After search results are returned and displayed.

Required fields for this event: event (_search), properties.key, properties.session, properties.query, properties._vid.

Note: To track searches that returned no results, set properties.totalHits to 0.

{
  "event": "_search",
  "properties": {
    "key": "<tracking-key>",
    "session": "<session-id>",
    "query": "sitecore",
    "language": "en",
    "model": "CorpSiteModel",
    "_vid": "<visitor-id>",
    "impressions": [
      { "cDocId": "https://example.com/doc-1", "cDocTitle": "Doc 1", "position": 1 }
    ]
  }
}

_questionanswer

What it tracks: A Smart Answer interaction when a user asks a question and receives an AI-generated answer.

When to send it: When the Smart Answer response is returned for a question query.

Required fields for this event: event (_questionanswer), properties.key, properties.session, properties.question, properties.answer, properties.is_question, properties._vid.

Note: properties.is_question is the boolean question flag returned by the Smart Answer API response (I_AM_A_QUESTION).

{
  "event": "_questionanswer",
  "properties": {
    "key": "<tracking-key>",
    "session": "<session-id>",
    "question": "what versions of solr does searchstax support",
    "answer": "SearchStax supports ...",
    "is_question": true,
    "language": "en",
    "model": "CorpSiteModel",
    "_vid": "<visitor-id>"
  }
}

_related_search

What it tracks: Related-search suggestions returned for a query and the suggestion impressions shown to the user.

When to send it: After related-search suggestions are returned and rendered.

Required fields for this event: event (_relatedsearch), properties.key, properties.session, properties.query, properties._vid.

Note: To track related-search requests that returned no results, set properties.totalHits to 0.

{
  "event": "_relatedsearch",
  "properties": {
    "key": "<tracking-key>",
    "session": "<session-id>",
    "query": "solr",
    "language": "en",
    "model": "CorpSiteModel",
    "_vid": "<visitor-id>",
    "impressions": [
      { "relatedSearch": "managed solr", "position": 1 }
    ]
  }
}

_searchclick

What it tracks: A click on a search result document for relevance and click-through analytics.

When to send it: When a user clicks a result from the search results list.

Required fields for this event: event (_searchclick), properties.key, properties.session, properties.query, properties.cDocId, properties.cDocTitle, properties.position, properties._vid.

Note: properties.position is the absolute result position in the full result set (not per-page position).

{
  "event": "_searchclick",
  "properties": {
    "key": "<tracking-key>",
    "session": "<session-id>",
    "query": "sitecore",
    "language": "en",
    "model": "CorpSiteModel",
    "cDocId": "https://example.com/doc-2",
    "cDocTitle": "Doc 2",
    "position": 2,
    "_vid": "<visitor-id>"
  }
}

_answersourceclick

What it tracks: A click on a source link from a Smart Answer response.

When to send it: When a user clicks a citation or source URL in a Smart Answer.

Required fields for this event: event (_answersourceclick), properties.key, properties.session, properties.href, properties.question, properties.answer, properties._vid.

Note: properties.href is the source URL the user clicked from the Smart Answer.

{
  "event": "_answersourceclick",
  "properties": {
    "key": "<tracking-key>",
    "session": "<session-id>",
    "href": "https://www.searchstax.com/docs/example",
    "question": "what versions of solr does searchstax support",
    "answer": "SearchStax supports ...",
    "language": "en",
    "model": "CorpSiteModel",
    "_vid": "<visitor-id>"
  }
}

_relatedsearchclick

What it tracks: A click on a related-search suggestion.

When to send it: When a user clicks one of the related-search terms shown for a query.

Required fields for this event: event (_relatedsearchclick), properties.key, properties.session, properties.query, properties.relatedSearch, properties.position, properties._vid.

Note: properties.position is the absolute position of the related-search term in the full related-search list.

{
  "event": "_relatedsearchclick",
  "properties": {
    "key": "<tracking-key>",
    "session": "<session-id>",
    "query": "sitecore",
    "language": "en",
    "model": "CorpSiteModel",
    "relatedSearch": "sitecore 7",
    "position": 2,
    "_vid": "<visitor-id>"
  }
}

_searchSatisfaction

What it tracks: Qualitative feedback on search experience, including a score and optional comments.

When to send it: When a user submits search satisfaction feedback in your UI.

Required fields for this event: event (_searchSatisfaction), properties.key, properties.session, properties.score, properties._vid.

Note: properties.score is a 0-10 rating of the search experience.

{
  "event": "_searchSatisfaction",
  "properties": {
    "key": "<tracking-key>",
    "session": "<session-id>",
    "score": 10,
    "comments": "Very good search experience",
    "language": "en",
    "model": "CorpSiteModel",
    "_vid": "<visitor-id>"
  }
}

Response Notes

Successful requests return 204 No Content.

HTTP Status Codes and Error Handling

Pagination

Not applicable. This is an ingestion endpoint.

Rate Limits and Backoff

• Shared app-level guidance: 20+ requests/second.
• Retry-After is not guaranteed for shared limit responses.
• Implement retry delays for repeated 429 conditions.

Shared API Foundations

Use these shared references for authentication, request and response structure, and pagination behavior used across Site Search APIs:

• Authentication and Authorization
• Request and Response Conventions
• Pagination