Browse all documentation

Search report

Read saved Google or Bing search metrics: clicks, impressions, click-through rate and position.

GET/api/v1/brands/{brandId}/reports/searchread

Call the corresponding get_search_report MCP tool with JSON arguments. Supply brandId and other path values as named arguments when the endpoint has them.

Request details

Required scope: A valid read or write token. Increase offset by limit for each page while paging.hasMore is true.

Request example
curl --request GET \
  --url "https://searchseal.com/api/v1/brands/b7e4c2a0-5d1f-4c8e-9a3b-2f6d8e1c4a70/reports/search?source=google&dimensions=query,page" \
  --header "Authorization: Bearer $SEARCHSEAL_TOKEN"

Dates retain each source’s calendar. meta.dataThrough.google and .bing show the latest saved daily totals, independent of report filters.

Request parameters

NameLocationRequiredTypeDescription
brandIdpathYesuuidAn active brand ID returned by the brand list.
sourcequeryYes"google" | "bing"Select the search provider for this report.
startDatequeryNoYYYY-MM-DDInclusive starting date. Defaults to 27 days before endDate; the window allows 90 days. Search dates follow the source calendar.
endDatequeryNoYYYY-MM-DDInclusive ending date, defaulting to today in the account time zone. A future date returns 400 invalid_request with field code future_date.
dimensionsqueryNostringChoose query, page or date, comma-separated. Google requires page with query, otherwise 400 invalid_request with query_needs_page. Bing permits query or page alone for weekly data, or date alone. Omit for totals.
limitqueryNointegerPage size from 1 to 100; defaults to 50.
offsetqueryNointegerNumber of preceding items to skip; defaults to 0.

Response fields

Response body example
{
  "source": "google",
  "items": [
    {
      "query": "ubud boutique villa",
      "page": "https://example.com/villas",
      "clicks": 41,
      "impressions": 1320,
      "ctr": 0.0311,
      "position": 6.2
    }
  ],
  "paging": {
    "limit": 50,
    "offset": 0,
    "hasMore": false
  },
  "meta": {
    "generatedAt": "2026-09-26T08:15:02.114Z",
    "timeZone": "Asia/Jakarta",
    "dataThrough": {
      "answers": "2026-09-26",
      "google": "2026-09-23",
      "bing": "2026-09-24"
    }
  }
}
FieldTypeDescription
source"google" | "bing"Provider selected by the request.
query, page, datestringDimension values for this row’s combination.
clicksintegerRecorded search-result clicks.
impressionsintegerImpressions reported by the selected search source.
ctrnumberRatio of clicks to impressions, from 0 to 1; zero when impressions are zero.
positionnumber | nullAverage position weighted by impressions. Null without impressions or for Bing daily totals.

Successful REST responses from this endpoint include the shown meta fields. Read about data-through dates.

Possible errors

  • 400 invalid_request — An input failed validation. Field details may appear in errors.
  • 401 unauthorized — Authentication failed because the token is absent, unrecognized or revoked.
  • 403 forbidden — Account access or token permissions do not allow this request. Check the message for the cause.
  • 404 not_found — The resource is missing or unavailable to this account, including inactive brands.
  • 429 rate_limited — A quota was reached or could not be checked. Wait the Retry-After delay before retrying.
  • 500 server_error — The server failed to complete the operation.

For the shared error format, see status codes, quotas and retries. Next endpoint: List fixes.