Reporting API (REST)

Updated

The Reporting API retrieves analytics aggregates and top lists for search activity and clicks.

Endpoint Family

  • Method: GET
  • Base pattern: https://<analytics-reporting-host>/api/rest/analytics/v1/reporting/...

Common paths include:

  • /searches/searches
  • /clicks/clicks
  • /searches/power-search/searches
  • /clicks/power-search/clicks

UI Navigation

Find the reporting endpoint and key in Site Search > App Settings > All APIs > Analytics.

Analytics Reporting endpoint and key panel in Site Search app settings.

Authentication

Use reporting token authentication. 

Authorization: Token <reporting-key>

Request Parameters

Name Required Type Description
Authorization Yes header Use Authorization: Token <analytics-reporting-key>.
limit No query string Optional page-size bound for reporting result lists.
offset No query string Optional zero-based offset for paginated reporting lists.
language No query string Optional language code used to scope analytics reports. Both dash and underscore language-code variants are accepted and normalized automatically.

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

Request Example 

curl -sS --get \
  -H "Authorization: Token <analytics-reporting-key>" \
  --data-urlencode "limit=10" \
  --data-urlencode "offset=0" \
  "https://<analytics-reporting-host>/api/rest/analytics/v1/reporting/searches/searches"

Response Notes

Successful responses return JSON objects that include aggregate metrics and list payloads.

Common list fields include:

  • topSearches
  • topNoResultSearches
  • topNoClickSearches
  • mostClicked
  • leastClicked

HTTP Status Codes and Error Handling

HTTP Code When It Happens Typical Response Body What to Do
200 Request succeeds JSON aggregate or list payload Process report data
401 Invalid token {"detail":"Not authenticated"} Verify reporting token
403 Wrong auth header format, for example missing Token prefix {"detail":"Not authenticated"} Use Authorization: Token <key>
422 Invalid query parameters, for example limit < 1 Validation detail payload Correct query values
429 Shared app-level rate or plan limit condition Too-many-requests response Retry with backoff

Pagination

Offset-based pagination is supported.

  • limit controls page size.
  • offset controls row start.

Rate Limits and Backoff

  • Endpoint-specific reporting limits are not documented separately.
  • Shared app-level guidance (20+ requests/second) and 429 handling apply.
  • Retry-After is not guaranteed. Use client-side retry delays.

Shared API Foundations

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

Articles in this section