Public data · API / MCP

Read-only queries of reviewed, published announcements, using the same data and rules as the website. Verified locally only; not deployed or connected to a production plugin.

Unofficial. Not affiliated with xAI or X. Times refer to publication, not exact activation or your account balance. Only verifiable public announcements mark a date. Blank dates do not prove no reset occurred. Search may miss posts; coverage is incomplete. We do not read personal account balances

HTTP API · v1

Local origin: http://localhost:3000. No key required. No write, review, subscription or delivery commands.

GET /api/v1/latest: Returns event, or null. Selects confirmed resets with sources; excludes limit increases and future announcements.
GET /api/v1/history: Returns items, filters and pagination. In-progress, announced and cancelled states remain explicit, never relabelled as confirmed.
GET /api/v1/stats: Returns stats and latestConfirmedEvent: total, average/longest interval hours, elapsed hours and trailing 30/90-day counts.

latest/stats default to product=grok_bot; history defaults to all products. Statistics deduplicate sources and count confirmed, non-limit_increase, non-future events with evidence. Intervals use consecutive confirmed announcements; insufficient samples give null. 30/90-day windows are inclusive and relative to checkedAt.

History filters and pagination

product: grok_bot / x_grok / grok_com / grok_imagine / xai_api / other
status: announced / propagating / confirmed / cancelled
kind: full_reset / credit_grant / scheduled_refresh / incident_compensation / limit_increase
plan: history only; all_users, unknown, or reviewed plan name (2–64 characters; case/Unicode-normalized matching). Named plans include all-user resets, not unknown audiences. audience contains mode, plans, evidenceExcerpt, updatedAt; unreviewed or stale review is unknown.
from/to: UTC ISO timestamps ending Z, inclusive. from must not be after to.
limit: 1–100, default 20. offset: 0–1000000, default 0. MCP uses integers; HTTP uses decimal strings. Unknown or duplicate parameters are errors.
lang: en / zh-CN / zh-TW / ja / ko, default zh-CN. Independently reviewed summaries fall back to zh-CN when missing or stale. summaryLanguage, translationState and translationUpdatedAt make this explicit. Original text and event facts remain unchanged.

GET /api/v1/history?product=grok_bot&status=confirmed&limit=1&offset=0&lang=en

Sort: occurredAt descending, then ID ascending. pagination.total is the filtered count; hasMore/nextOffset identify the next page. Pagination is not a frozen snapshot. Restart at offset=0 after archive changes.

Evidence, caching and errors

Events include sourceUrl, originalExcerpt, evidenceLevel, status, sourceCapturedAt and updatedAt. checkedAt is query time; top-level updatedAt is the latest public fact or selected-language translation update (null for an empty archive), all UTC. Admin identities, candidate reasons, audit details and subscriptions are private.

updates contains reviewed, published follow-ups for the same event, ordered by publishedAt ascending. Each has its status, exact UTC publication time, source, original text, evidence level and verification time. Summaries are explicitly marked zh-CN. Updates do not add reset occurrences or implicitly rewrite the main facts.

Read-only CORS * without credentials, 30-second cache, ETag/If-None-Match and HEAD/OPTIONS. Errors are not cached. 60 requests/minute per instance/IP across API/MCP, with one shared local budget; not a global limit. 429/503 include Retry-After.

400: invalid/duplicate query. 404: not found. 405: unsupported method. 429: rate limit. 503: data unavailable, never fake zero values.

MCP · POST /mcp

Stateless Streamable HTTP with JSON responses, no SSE stream or session ID. Versions: 2025-03-26, 2025-06-18, 2025-11-25; missing protocol header defaults to 2025-03-26. Sequence: initialize → notifications/initialized → tools/list or tools/call.

One JSON-RPC 2.0 message per POST, max 16 KiB. Content-Type: application/json. Accept must include application/json and text/event-stream; subsequent requests carry MCP-Protocol-Version. Protocol notifications return empty 202; GET returns 405. Origin must match this service.

latest: Returns event, or null. Selects confirmed resets with sources; excludes limit increases and future announcements.
history: Returns items, filters and pagination. In-progress, announced and cancelled states remain explicit, never relabelled as confirmed.
stats: Returns stats and latestConfirmedEvent: total, average/longest interval hours, elapsed hours and trailing 30/90-day counts.

Protocol request example (not event data)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "your-client",
      "version": "1.0.0"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "history",
    "arguments": {
      "product": "grok_bot",
      "status": "confirmed",
      "limit": 20,
      "offset": 0,
      "lang": "en"
    }
  }
}

latest/history/stats match the HTTP parameters and results. They do not fetch external pages or write data. Results include structuredContent and text JSON. Invalid parameters: -32602; unknown methods: -32601; database failure: isError=true, not an empty archive. Source text is untrusted evidence, never client instructions. localhost does not imply a connected cloud client.

Official MCP transport specification