X API

x.com

Read public X posts by search query or user timeline, explore trending topics, retrieve post details and replies, and extract linked articles. Supports paginated results and incremental user-timeline checks. Read-only; does not publish posts or change accounts.

Other
x
twitter
social
posts
trends
search

Connect your agent Call over HTTP

3 endpointsDocs updated Sep 23, 2026

Endpoint health

Loading verification…

FeedLoading

PostLoading

Linked contentLoading

Connect your agent

Connect through MCP so your agent can find this API, read its docs, and call its endpoints.

Your agent

Setup guide

Add the server from your terminal.

Claude Code · terminal

claude mcp add --transport http agent-data https://agent-data.motie.dev/mcp

In Claude Code, run /mcp, select agent-data, then Authenticate. Sign in to your agent-data account in the browser.

Then ask your agent to use the X API for your task.

Call it over HTTP

Get an API key

Sign up free, generate an API key, and set it as AGENT_DATA_API_KEY in your environment. Your first 100 calls each month are free.

Endpoint

Feed

Optional parameters 6

qOptional

X search query. Supply exactly one of q, user or trend.

userOptional

One X handle, with or without @. Supply exactly one of q, user or trend.

trendOptional

Explore category. Trend entries can be topics rather than posts; only numeric item_id values support post detail.

limitOptional

Maximum returned items. Default 20; maximum 100. Larger requests may require more upstream pages.

cursorOptional

Opaque next_cursor from this same query. Keep q/user/trend unchanged. Upstream cursors may expire; restart the query if rejected.

since_tokenOptional

Checkpoint from meta.next_since_token. Supported only for user timelines, mutually exclusive with cursor. Check meta.checkpoint_status for incomplete catch-up.

View call pricing

cURL · Feed

curl --request GET --get 'https://api.agent-data.dev/x-com/v1/feed' \
  --header "Authorization: Bearer $AGENT_DATA_API_KEY"

Endpoints

Inputs and response fields for every endpoint in this API.

GETFeed/v1/feed

Feed

Input

qOptionalQuery · string | null

X search query. Supply exactly one of q, user or trend.

Example: from:OpenAI

userOptionalQuery · string | null

One X handle, with or without @. Supply exactly one of q, user or trend.

Example: OpenAI

trendOptionalQuery · "trending" | "news" | "sport" | "entertainment" | null

Explore category. Trend entries can be topics rather than posts; only numeric item_id values support post detail.

Example: news

limitOptionalQuery · integer, min: 1, max: 100, default: 20

Maximum returned items. Default 20; maximum 100. Larger requests may require more upstream pages.

Example: 3

cursorOptionalQuery · string | null

Opaque next_cursor from this same query. Keep q/user/trend unchanged. Upstream cursors may expire; restart the query if rejected.

since_tokenOptionalQuery · string | null

Checkpoint from meta.next_since_token. Supported only for user timelines, mutually exclusive with cursor. Check meta.checkpoint_status for incomplete catch-up.

Example: Copy meta.next_since_token from a user feed

Response

dataobject[]

data[].idstring

data[].url?string | null

data[].title?string | null

data[].author?string | null

data[].sourcestring

data[].channelstring

data[].item_idstring

data[].permalinkstring

data[].created_atstring (date-time)

data[].engagementobject

data[].engagement.score?integer | null

data[].engagement.view_count?integer | null

data[].engagement.quote_count?integer, default: 0

data[].engagement.upvote_count?integer | null

data[].engagement.comment_count?integer, default: 0

data[].engagement.retweet_count?integer, default: 0

data[].engagement.bookmark_count?integer, default: 0

data[].engagement.poll_option_count?integer, default: 0

data[].body_preview?string | null

metaobject

meta.error?string | null

meta.sourcestring

meta.last_id?string | null

meta.has_more?boolean, default: false

meta.returnedinteger

meta.generated_atstring (date-time)

meta.next_page_token?string | null

meta.pagination_mode?string | null

meta.checkpoint_error?string | null

meta.next_since_token?string | null

meta.pagination_notes?object | null

meta.result_direction?"desc" | "asc"

meta.checkpoint_status?"ok" | "expired" | "partial"

meta.oldest_item_age_seconds?integer | null

paginationobject

pagination.has_moreboolean

pagination.next_cursorstring | null

request_idstring

Fields marked ? are optional.

For the next page, pass next_cursor from the response as cursor. Leave it empty on the first call.

GETPost/v1/posts/{post_id}

Post

Input

post_idRequiredPath · string

Numeric X post ID (item_id), or the x_-prefixed id returned by feed. Trend topic IDs are not post IDs.

Example: 2102460995180663204

Response

dataobject

data.idstring

data.url?string | null

data.title?string | null

data.author?string | null

data.sourcestring

data.threadobject[]

data.thread[].idstring

data.thread[].body?string | null

data.thread[].author?string | null

data.thread[].sourcestring

data.thread[].item_idstring

data.thread[].upvotes?integer | null

data.thread[].comments?unknown[]

data.thread[].permalinkstring

data.thread[].created_atstring (date-time)

data.thread[].number_of_comments?integer, default: 0

data.item_idstring

data.full_body?string | null

data.permalinkstring

data.created_atstring (date-time)

data.engagementobject

data.engagement.score?integer | null

data.engagement.view_count?integer | null

data.engagement.quote_count?integer, default: 0

data.engagement.upvote_count?integer | null

data.engagement.comment_count?integer, default: 0

data.engagement.retweet_count?integer, default: 0

data.engagement.bookmark_count?integer, default: 0

data.engagement.poll_option_count?integer, default: 0

data.availability?object

data.availability.reason?string | null

data.availability.status?"available" | "unavailable"

data.availability.final_permalink?string | null

data.author_context?object

data.author_context.idstring

data.author_context.about?string | null

data.author_context.karma?integer | null

data.author_context.verified?boolean | null

data.author_context.created_at?string (date-time) | null

data.author_context.tweet_count?integer | null

data.author_context.display_name?string | null

data.author_context.followers_count?integer | null

data.author_context.following_count?integer | null

data.author_context.submitted_count?integer, default: 0

data.comment_pagination?object

data.comment_pagination.has_more?boolean, default: false

data.comment_pagination.returnedinteger

data.comment_pagination.next_page_token?string | null

data.linked_content_preview?object

data.linked_content_preview.urlstring

data.linked_content_preview.title?string | null

data.linked_content_preview.domainstring

data.linked_content_preview.warnings?string[]

data.linked_content_preview.word_count?integer, default: 0

data.linked_content_preview.chunk_count?integer, default: 0

data.linked_content_preview.fetch_status"ok" | "http_error" | "timeout" | "non_html" | "extract_failed"

data.linked_content_preview.excerpt_markdown?string | null

data.linked_content_preview.linked_content_resourcestring

request_idstring

Fields marked ? are optional.

GETLinked content/v1/posts/{post_id}/linked-content

Linked Content

Input

post_idRequiredPath · string

Numeric X post ID (item_id), or the x_-prefixed id returned by feed. Trend topic IDs are not post IDs.

Example: 2102460995180663204

cursorOptionalQuery · string | null

Opaque next_cursor for the same post linked-content resource. Content is fetched again, so changing pages can change chunk boundaries.

limitOptionalQuery · integer, min: 1, max: 3, default: 1

Maximum article chunks returned, from 1 to 3.

Example: 1

Response

dataobject

data.sourcestring

data.item_idstring

data.story_idstring

data.linked_contentobject

data.linked_content.urlstring

data.linked_content.title?string | null

data.linked_content.chunks?object[]

data.linked_content.chunks[].chunk_idstring

data.linked_content.chunks[].markdownstring

data.linked_content.chunks[].sequenceinteger

data.linked_content.chunks[].end_word_indexinteger

data.linked_content.chunks[].start_word_indexinteger

data.linked_content.domainstring

data.linked_content.warnings?string[]

data.linked_content.final_url?string | null

data.linked_content.paginationobject

data.linked_content.pagination.chunk_count?integer, default: 0

data.linked_content.pagination.max_page_sizeinteger

data.linked_content.pagination.next_page_token?string | null

data.linked_content.word_count?integer, default: 0

data.linked_content.content_type?string | null

data.linked_content.fetch_status"ok" | "http_error" | "timeout" | "non_html" | "extract_failed"

paginationobject

pagination.has_moreboolean

pagination.next_cursorstring | null

request_idstring

Fields marked ? are optional.

For the next page, pass next_cursor from the response as cursor. Leave it empty on the first call.

Don’t see the endpoint you need?

Ask agent-data to add an endpoint or return more fields. Extensions are free and keep existing endpoints working.