Browse all documentation

List articles

List articles, newest first, with monthly usage.

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

Call the corresponding list_articles 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/articles" \
  --header "Authorization: Bearer $SEARCHSEAL_TOKEN"

Request parameters

NameLocationRequiredTypeDescription
brandIdpathYesuuidAn active brand ID returned by the brand list.
statusqueryNo"queued" | "writing" | "ready" | "failed"Only articles in this state.

Response fields

Response body example
{
  "items": [
    {
      "id": "d8b3f1c6-4a2e-4d9b-8c7f-3e1a5b9d2c64",
      "brandId": "b7e4c2a0-5d1f-4c8e-9a3b-2f6d8e1c4a70",
      "fixId": "f5c2e8a1-9d3b-4e7f-a0c6-1b4d7e9f2a38",
      "questionId": "e3a9d1e2-7b4c-4f60-8e2a-9c1d5b7f3e21",
      "kind": "new_page",
      "pageUrl": null,
      "language": "en",
      "status": "ready",
      "title": "Best villa rentals in Bali for families",
      "checkScore": 83,
      "edited": false,
      "error": null,
      "source": "api",
      "createdAt": "2026-09-26T08:14:51.402Z",
      "finishedAt": "2026-09-26T08:16:20.118Z",
      "format": "guide",
      "length": "standard",
      "phase": null,
      "phaseAt": null,
      "publishedAt": null,
      "publishedUrl": null,
      "publishCheck": null,
      "proof": null
    }
  ],
  "paging": {
    "limit": 50,
    "offset": 0,
    "hasMore": false
  },
  "articlesUsed": 3,
  "articlesMax": 80,
  "meta": {
    "generatedAt": "2026-09-26T08:15:02.114Z",
    "timeZone": "Asia/Jakarta"
  }
}
FieldTypeDescription
items[].iduuidArticle ID.
items[].fixIduuid | nullThe fix it was written from.
items[].questionIduuid | nullThe tracked question it answers.
items[].kind"new_page" | "rewrite"A new page, or a rewrite of pageUrl on the brand site.
items[].status"queued" | "writing" | "ready" | "failed"Writing takes a minute or two. A failed article counts toward your monthly limit only if AI processing already ran; error explains why it failed.
items[].titlestring | nullThe page title once ready.
items[].checkScoreinteger | nullThe draft page check score, 0 to 100.
items[].editedbooleanWhether the owner has edited the draft.
items[].format"guide" | "comparison" | "faq" | "how_to"Optional page format: guide, comparison, faq or how_to, chosen from the fix or question if omitted.
items[].length"short" | "standard" | "long"Optional length: short (about 600 words), standard (about 1,000, default) or long (about 1,600).
items[].phase"reading" | "writing" | "checking" | nullCurrent phase while queued or writing: reading_sources, writing or checking; null when finished or failed.
items[].phaseAtstring | nullWhen the current phase started, in ISO 8601 format.
items[].publishedAtstring | nullWhen the owner marked it published.
items[].publishedUrlstring | nullWhere the page went live.
items[].publishCheckobject | nullLive page check when marked published, outside your limit: { id, status, score, error }.
items[].proofobject | nullBefore-and-after results for the completed fix: status (waiting, measured, not_comparable, not_measured), metric, before, after, change, dueAt, reason, and beforeAnswers/afterAnswers as { named, total }.
articlesUsedintegerArticles used this month (UTC).
articlesMaxintegerArticles included a month.

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: Write an article.