X post and profile JSON, field by field: a reference for agents
By Steven Van ·
A reference for the free X endpoints lists every field, type, rate-limit header and error shape, plus the edge cases agents need to handle.
The free Unif API X endpoints now have a field-by-field JSON reference written for agents. It covers posts, profiles, paged lists, rate limits and errors, with types and edge cases. The endpoints are free to use with no login and are rate-limited per visitor.
Conventions
- Field names are camelCase.
- Ids are strings, because X ids exceed 2^53 and lose precision as JSON numbers. This includes ids in URLs and cursors.
- Dates are ISO 8601 in UTC, such as 2026-10-05T22:33:56.000Z.
- Counts are integers. A count X does not report is left out rather than set to 0, so code should test for the key ("views" in post.metrics) instead of comparing to zero.
- Post URLs are canonical x.com URLs. Media URLs point to X's CDN and are not re-hosted.
Records and edge cases
Three records are returned: post, profile, and a page wrapper around lists. A post carries text, createdAt, an author, a metrics object (likes, reposts, replies, quotes, bookmarks, and optional views) and a media array. The reference calls out several cases a program has to handle:
- A repost returns the original post plus a repostedBy object with the reposting account's id, handle and name.
- A quote post nests the quoted post one level. A quote inside a quote is not expanded.
- A protected account returns its counts but no posts.
- Views are reported on most posts but not all.
- The reply count is X's own figure and can exceed the number of readable public replies.
The profile endpoint adds engagementRate, the average of likes, replies, reposts and quotes per original post on the page, divided by followers, as a percentage. Reposts are excluded. For an account with 90 million followers the value is small (0.0058), which the reference says is correct.
Pages, trends and communities
Lists come back as items, hasMore and nextCursor. Cursors are opaque and are passed back as cursor=, never parsed. Page sizes are 10 posts on profile, 12 on media, 20 on replies, search and communities, 50 on followers, and 30 trends. Trends carry an optional postCount, which is absent for most locations today.
Rate limits and errors
Every response includes X-RateLimit-Limit (20), X-RateLimit-Remaining and X-RateLimit-Reset, the Unix time the current 10-minute window ends. A search costs 2 units and everything else 1. A 429 adds Retry-After.
Non-2xx responses share one shape, an error object with type and message. The types are validation_error (400), not_found (404), rate_limited (429), upstream_error (502), and upstream_unavailable and not_configured (both 503). Code should branch on type, since message can change.
Markdown mode
Adding format=md or sending Accept: text/markdown renders the same record as Markdown, which the post describes as the cheapest way to put a profile or thread into a model's context. Each tool's Markdown page carries a captured sample response, and /llms.txt lists all eight endpoints with an example URL. The metered X / Twitter API uses the same field names behind a workspace key, so code written against the free endpoints moves over without edits.
