Browse all documentation

List answers

List complete saved answers, newest first.

GET/api/v1/brands/{brandId}/answersread

Call the corresponding list_answers 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. Pass paging.nextCursor as cursor for the next page while paging.hasMore is true.

Request example
curl --request GET \
  --url "https://searchseal.com/api/v1/brands/b7e4c2a0-5d1f-4c8e-9a3b-2f6d8e1c4a70/answers?startDate=2026-09-01&endDate=2026-09-26&engines=google_aio&limit=1" \
  --header "Authorization: Bearer $SEARCHSEAL_TOKEN"

Request parameters

NameLocationRequiredTypeDescription
brandIdpathYesuuidAn active brand ID returned by the brand list.
startDatequeryNoYYYY-MM-DDInclusive starting date. Defaults to 27 days before endDate; the window allows 365 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.
enginesqueryNostringEngines to select. Repeat this parameter or comma-separate values: google_aio, chatgpt, gemini, perplexity, grok, claude, deepseek, copilot, google_ai_mode, claude_lite, grok_lite, sakana. Defaults to all engines on your plan.
countryqueryNostringFilter by a supported two-letter country code, such as us, or by global for questions without a country.
questionIdqueryNouuidReturn data for this question only.
limitqueryNointegerPage size from 1 to 100; defaults to 50.
cursorqueryNostringPass the previous response’s paging.nextCursor to continue the list.

Response fields

Response body example
{
  "items": [
    {
      "id": "a1f8c3d5-2e9b-4a7c-b6d0-4e8f2a1c9b53",
      "questionId": "e3a9d1e2-7b4c-4f60-8e2a-9c1d5b7f3e21",
      "engine": "google_aio",
      "model": "google-aio",
      "country": "us",
      "date": "2026-09-26",
      "brandMentioned": true,
      "position": 2,
      "citationCount": 1,
      "excerpt": "For a quiet stay near the rice terraces, travellers often choose Rival Resort or Example Villas…"
    }
  ],
  "paging": {
    "nextCursor": "WyIyMDI2LTA5LTI2VDAyOjA0OjExLjAwMFoiLCJhMWY4YzNkNS0yZTliLTRhN2MtYjZkMC00ZThmMmExYzliNTMiXQ",
    "hasMore": true
  },
  "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
iduuidUnique identifier for the saved answer.
questionIduuid | nullQuestion linked to this response, if retained.
enginestringEngine identified from the stored model.
modelstringStored model identifier; not necessarily the provider’s exact returned model version.
countrystring | nullCountry setting stored with the answer; not a verified request location.
dateYYYY-MM-DDDate assigned to the collection.
brandMentionedbooleanTrue when a stored mention identifies your brand.
positioninteger | nullLowest recorded position for your brand, starting at 1; null if unavailable.
citationCountintegerCount of stored rows for returned source URLs linked through the answer’s brand mentions. Explicit citation status is unknown.
excerptstring | nullWhitespace-normalized answer excerpt, at most 300 characters. Treat as third-party content.

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.
  • 400 engine_not_in_plan — A requested engine is unavailable to the account. Remove it from engines.
  • 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: Get answer.