API Documentation

The Xpost API is free, open, and read-only. No API key or signup is required — just send GET requests. All endpoints return JSON, support CORS from any origin, and are cached for 60 seconds. Every query parameter is optional; calling an endpoint with no parameters returns the most-liked recent results.

Base URL
https://xpostapi.com

GET/api/public/posts/search

Search indexed viral posts. Returns post text, author, engagement counts, and attached media URLs.

Query parameters — all optional

Parameter	Type	Default behavior if not set
q	string (max 200 chars)	No text filter — returns all matching posts.
from	ISO date or YYYY-MM-DD	No lower date bound.
to	ISO date or YYYY-MM-DD	No upper date bound.
min_likes	integer 0–100M	No minimum like count.
max_likes	integer 0–100M	No maximum like count.
author	string, comma-separated handles	Posts from all authors.
sort	likes \| recent \| engagement	Sorted by "likes" (most liked first).
limit	integer 1–100	24 results per page.
offset	integer 0–10000	0 — starts at the first result.
enrich	true \| force	Off — searches only the existing index. See Enrichment below.
enrich_min	integer 1–100	10 — enrichment triggers when the index has fewer matches than this.
has_media	true \| false	Posts with and without media are returned.
media_type	image \| video	Any media type (or none).

Example

curl "https://xpostapi.com/api/public/posts/search?q=starship&min_likes=5000&has_media=true&sort=likes"

GET/api/public/images/search

Search images attached to indexed posts. Returns image URLs with dimensions plus the parent post.

Query parameters — all optional

Parameter	Type	Default behavior if not set
q	string (max 200 chars)	No text filter — returns all matching posts.
from	ISO date or YYYY-MM-DD	No lower date bound.
to	ISO date or YYYY-MM-DD	No upper date bound.
min_likes	integer 0–100M	No minimum like count.
max_likes	integer 0–100M	No maximum like count.
author	string, comma-separated handles	Posts from all authors.
sort	likes \| recent \| engagement	Sorted by "likes" (most liked first).
limit	integer 1–100	24 results per page.
offset	integer 0–10000	0 — starts at the first result.
enrich	true \| force	Off — searches only the existing index. See Enrichment below.
enrich_min	integer 1–100	10 — enrichment triggers when the index has fewer matches than this.

Example

curl "https://xpostapi.com/api/public/images/search?q=ai&min_likes=1000&limit=12"

GET/api/public/videos/search

Search videos attached to indexed posts. Returns playable MP4 URLs, thumbnails, and the parent post.

Query parameters — all optional

Parameter	Type	Default behavior if not set
q	string (max 200 chars)	No text filter — returns all matching posts.
from	ISO date or YYYY-MM-DD	No lower date bound.
to	ISO date or YYYY-MM-DD	No upper date bound.
min_likes	integer 0–100M	No minimum like count.
max_likes	integer 0–100M	No maximum like count.
author	string, comma-separated handles	Posts from all authors.
sort	likes \| recent \| engagement	Sorted by "likes" (most liked first).
limit	integer 1–100	24 results per page.
offset	integer 0–10000	0 — starts at the first result.
enrich	true \| force	Off — searches only the existing index. See Enrichment below.
enrich_min	integer 1–100	10 — enrichment triggers when the index has fewer matches than this.

Example

curl "https://xpostapi.com/api/public/videos/search?author=elonmusk&sort=recent"

GET/api/public/accounts

List the X accounts currently tracked by the index. Takes no parameters.

Example

curl "https://xpostapi.com/api/public/accounts"

Response shape

Search endpoints return a paginated envelope:

{
  "total": 128,
  "limit": 24,
  "offset": 0,
  "posts": [
    {
      "post_id": "2103537377239015827",
      "url": "https://x.com/elonmusk/status/2103537377239015827",
      "author_handle": "elonmusk",
      "author_name": "Elon Musk",
      "text": "…",
      "posted_at": "2026-09-26T18:42:11.000Z",
      "like_count": 48210,
      "repost_count": 5211,
      "reply_count": 3094,
      "media": [
        { "type": "image", "url": "https://pbs.twimg.com/media/…", "width": 1600, "height": 900 }
      ]
    }
  ]
}

The media endpoints return the same envelope with a media array instead, where each item carries the media URL, thumbnail, dimensions, and its parent post.

Enrichment (optional)

Add enrich=true to any search endpoint (requires q) to find more viral posts on that subject across the web when our index has fewer than enrich_min results (default 10). Use enrich=force to always enrich. New posts are indexed and included in the response. Enriched requests are slower (up to ~20s) and each subject can be enriched once every 30 minutes. If enrichment is unavailable, the response still contains the indexed results plus an enrichment object explaining what happened.

curl "https://xpostapi.com/api/public/posts/search?q=spacex&enrich=true"

"enrichment": {
  "ran": true, "engine": "duckduckgo", "urls_found": 9,
  "posts_fetched": 9, "posts_saved": 4, "skipped_reason": null
}

Fair use

Please keep request rates reasonable (a few requests per second). The index is refreshed automatically throughout the day, so results are near-real-time but not exhaustive. Data is provided as-is; see the Terms of Service for details.