# X post and profile JSON, field by field: a reference for agents By Steven Van · 2026-10-07 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. ![Unif API]() Unif API Prebuilt AI marketing agents for SEO, GEO, influencer research, social listening, and competitor analysis — run them inside Claude, ChatGPT, or Codex over one MCP server. [View Unif API →]() Sources [Original source]() [Read X post and profile JSON, field by field: a reference for agents on Creators Toolbox]() --- Canonical source: https://creatorstoolbox.com/blog/unif-api-x-post-and-profile-json-field-by-field-a-reference-for-agents