API reference

The live `/v1` read surface, in one place.

Each section lists the endpoint purpose, parameters, response shape, credit cost, and a request sample. Use /v1 for new integrations; /docs/x-api-compatible covers the official-style /2 migration layer.

Try it without an account

Run one real request right now on a shared demo key — live data, in the same response envelope your integration will use:

curl "https://xfetch.io/api/demo"            # profile.lookup — profile + recent tweets
curl "https://xfetch.io/api/demo?run=search" # search.recent — X-style operator query

Demo responses are shared across visitors and refresh about every minute. Sign in with Google for your own key, 1,000 free credits, and full rate limits.

Auth

Send your xfetch API key as a bearer token on every customer API request.

Authorization: Bearer $XFETCH_API_KEY

Credits

/v1 responses include meta.credits.charged and meta.credits.remaining. New accounts receive 1,000 credits; failed validation, auth failures, insufficient credits, rate limits, and service-side failures are not charged. See pricing for the credits cost of each endpoint.

Pagination

Paginated endpoints use next_token and return meta.pagination.next_token only when another page exists. limit is endpoint-specific: recent search allows up to 20, trends allows up to 100, graph mode=ids allows up to 5000, and continuation-only endpoints do not expose limit. Tokens are opaque — do not parse them.

Errors

Every endpoint returns the same public error envelope on failure. Standard codes: invalid_request (400), invalid_api_key / revoked_api_key (401), insufficient_credits (402), endpoint_not_found (404), rate_limited (429), internal_error (500), service_unavailable (503).

A 402 insufficient_credits body also includes a help_url pointing to billing, where you can add credits or choose a plan — the next step when a request is rejected for credits.

Basic Reads

GET/v1/trendsBasic Reads1 base + 1 per item#

Fetch ranked trends for a WOEID (default `1` = worldwide).

curl 'https://api.xfetch.io/v1/trends?woeid=1' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`woeid`	query	`string`	optional		WOEID (Where On Earth ID); defaults to 1 (worldwide).
`limit`	query	`integer`	optional	default: 20

Response

{
  "data": [
    {
      "name": "#xfetch",
      "url": "https://example.com/search?q=xfetch",
      "tweet_volume": 1200
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    }
  }
}

GET/v1/search/recentBasic Reads1 base + 1 per item#

Search recent tweets matching a query for social listening and monitoring jobs.

curl 'https://api.xfetch.io/v1/search/recent?query=xfetch%20lang%3Aen%20-filter%3Areplies&sort_order=recency' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`query`	query	`string`	required		Search text. Supports X-style operators: "quoted phrases", OR, () grouping, #hashtag, $cashtag, from:, lang:, since:/until: (YYYY-MM-DD), min_faves:, min_retweets:, filter:links, and - negation (e.g. -filter:replies).
`sort_order`	query	`string`	optional	recency \| relevancy
`limit`	query	`integer`	optional	default: 20	Page size for search-backed results.
`next_token`	query	`string`	optional

Response

{
  "data": [
    {
      "id": "1234567890123456789",
      "text": "xfetch ships /v1 today.",
      "author_id": "783214",
      "created_at": "2026-05-23T12:00:00.000Z",
      "lang": "en",
      "conversation_id": "1234567890123456789",
      "possibly_sensitive": false,
      "like_count": 5,
      "retweet_count": 1,
      "reply_count": 0,
      "quote_count": 0,
      "bookmark_count": 0,
      "is_quote_status": false,
      "entities": {
        "hashtags": [],
        "urls": [],
        "mentions": []
      }
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    },
    "pagination": {
      "next_token": "tok_2"
    }
  }
}

GET/v1/users/{id}Basic ReadsFlat 1 credit#

Look up one user by numeric ID.

curl 'https://api.xfetch.io/v1/users/783214' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required

Response

{
  "data": {
    "id": "783214",
    "username": "xfetch",
    "name": "xfetch",
    "description": "Self-serve X/Twitter data API for anyone who needs the data.",
    "created_at": "2024-01-01T00:00:00.000Z",
    "verified": false,
    "protected": false,
    "profile_image_url": "https://example.com/avatar.png",
    "follower_count": 12000,
    "following_count": 18,
    "tweet_count": 240,
    "status": "active"
  },
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 1,
      "remaining": 999
    }
  }
}

GET/v1/users/by-username/{username}Basic ReadsFlat 1 credit#

Look up one user by case-insensitive username.

curl 'https://api.xfetch.io/v1/users/by-username/xfetch' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`username`	path	`string`	required

Response

{
  "data": {
    "id": "783214",
    "username": "xfetch",
    "name": "xfetch",
    "description": "Self-serve X/Twitter data API for anyone who needs the data.",
    "created_at": "2024-01-01T00:00:00.000Z",
    "verified": false,
    "protected": false,
    "profile_image_url": "https://example.com/avatar.png",
    "follower_count": 12000,
    "following_count": 18,
    "tweet_count": 240,
    "status": "active"
  },
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 1,
      "remaining": 999
    }
  }
}

GET/v1/usersBasic Reads1 base + 1 per item#

Look up multiple users in one call by comma-separated IDs.

curl 'https://api.xfetch.io/v1/users?ids=783214' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`ids`	query	`string`	required		Comma-separated IDs.

Response

{
  "data": [
    {
      "id": "783214",
      "username": "xfetch",
      "name": "xfetch",
      "description": "Self-serve X/Twitter data API for anyone who needs the data.",
      "created_at": "2024-01-01T00:00:00.000Z",
      "verified": false,
      "protected": false,
      "profile_image_url": "https://example.com/avatar.png",
      "follower_count": 12000,
      "following_count": 18,
      "tweet_count": 240
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    }
  }
}

GET/v1/users/{id}/tweetsBasic Reads1 base + 1 per item#

List a user's recent original tweets and retweets in reverse-chronological order.

curl 'https://api.xfetch.io/v1/users/783214/tweets' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required
`next_token`	query	`string`	optional

Response

{
  "data": [
    {
      "id": "1234567890123456789",
      "text": "xfetch ships /v1 today.",
      "author_id": "783214",
      "created_at": "2026-05-23T12:00:00.000Z",
      "lang": "en",
      "conversation_id": "1234567890123456789",
      "possibly_sensitive": false,
      "like_count": 5,
      "retweet_count": 1,
      "reply_count": 0,
      "quote_count": 0,
      "bookmark_count": 0,
      "is_quote_status": false,
      "entities": {
        "hashtags": [],
        "urls": [],
        "mentions": []
      }
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    },
    "pagination": {
      "next_token": "tok_2"
    }
  }
}

GET/v1/users/{id}/tweets/repliesBasic Reads1 base + 1 per item#

List a user's recent tweets including reply tweets.

curl 'https://api.xfetch.io/v1/users/783214/tweets/replies' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required
`next_token`	query	`string`	optional

Response

{
  "data": [
    {
      "id": "1234567890123456789",
      "text": "@user great question!",
      "author_id": "783214",
      "created_at": "2026-05-23T12:00:00.000Z",
      "lang": "en",
      "conversation_id": "1234567890120000000",
      "in_reply_to_user_id": "42",
      "possibly_sensitive": false,
      "like_count": 2,
      "retweet_count": 0,
      "reply_count": 1,
      "quote_count": 0,
      "bookmark_count": 0,
      "is_quote_status": false,
      "referenced_tweets": [
        {
          "type": "replied_to",
          "id": "1234567890120000000"
        }
      ],
      "entities": {
        "hashtags": [],
        "urls": [],
        "mentions": []
      }
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    },
    "pagination": {
      "next_token": "tok_2"
    }
  }
}

GET/v1/users/{id}/mediaBasic Reads1 base + 1 per item#

List a user's recent tweets that include compact media objects.

curl 'https://api.xfetch.io/v1/users/783214/media' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required
`next_token`	query	`string`	optional

Response

{
  "data": [
    {
      "id": "1234567890123456789",
      "text": "New dashboard screenshot.",
      "author_id": "783214",
      "created_at": "2026-05-23T12:00:00.000Z",
      "lang": "en",
      "like_count": 18,
      "retweet_count": 3,
      "reply_count": 1,
      "quote_count": 0,
      "bookmark_count": 2,
      "is_quote_status": false,
      "entities": {
        "hashtags": [],
        "urls": [],
        "mentions": []
      },
      "media": [
        {
          "type": "photo",
          "url": "https://example.com/media.jpg"
        }
      ]
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    },
    "pagination": {
      "next_token": "tok_2"
    }
  }
}

GET/v1/users/{id}/followersBasic Reads1 base + 1 per 50 items (varies by mode)#

List follower IDs for low-cost audience-graph reads.

curl 'https://api.xfetch.io/v1/users/783214/followers?mode=ids' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required
`next_token`	query	`string`	optional
`mode`	query	`string`	optional	ids \| profiles
`limit`	query	`integer`	optional	default: 200	Supported only when mode=ids.

Response

{
  "data": [
    {
      "id": "783214"
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    },
    "pagination": {
      "next_token": "tok_2"
    }
  }
}

GET/v1/users/{id}/verified-followersBasic Reads1 base + 1 per item#

List a user's verified followers — a high-signal subset of followers for audience and influence analysis.

curl 'https://api.xfetch.io/v1/users/783214/verified-followers' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required
`next_token`	query	`string`	optional

Response

{
  "data": [
    {
      "id": "783214",
      "username": "xfetch",
      "name": "xfetch",
      "description": "Self-serve X/Twitter data API for anyone who needs the data.",
      "created_at": "2024-01-01T00:00:00.000Z",
      "verified": true,
      "protected": false,
      "profile_image_url": "https://example.com/avatar.png",
      "follower_count": 12000,
      "following_count": 18,
      "tweet_count": 240
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    },
    "pagination": {
      "next_token": "tok_2"
    }
  }
}

GET/v1/users/{id}/followingBasic Reads1 base + 1 per 50 items (varies by mode)#

List followed account IDs for low-cost audience-graph reads.

curl 'https://api.xfetch.io/v1/users/783214/following?mode=ids' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required
`next_token`	query	`string`	optional
`mode`	query	`string`	optional	ids \| profiles
`limit`	query	`integer`	optional	default: 200	Supported only when mode=ids.

Response

{
  "data": [
    {
      "id": "783214"
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    },
    "pagination": {
      "next_token": "tok_2"
    }
  }
}

GET/v1/users/relationshipBasic ReadsFlat 1 credit#

Check whether source follows target and whether target follows back.

curl 'https://api.xfetch.io/v1/users/relationship?source=elonmusk&target=SpaceX' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`source`	query	`string`	required
`target`	query	`string`	required

Response

{
  "data": {
    "source_user_id": "44196397",
    "source_username": "elonmusk",
    "target_user_id": "34743251",
    "target_username": "SpaceX",
    "following": true,
    "followed_by": true
  },
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 1,
      "remaining": 999
    }
  }
}

GET/v1/tweets/{id}Basic ReadsFlat 1 credit#

Look up one tweet by ID with enriched metrics, language, entities, and context fields.

curl 'https://api.xfetch.io/v1/tweets/1234567890123456789' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required

Response

{
  "data": {
    "id": "1234567890123456789",
    "text": "xfetch ships /v1 today.",
    "author_id": "783214",
    "created_at": "2026-05-23T12:00:00.000Z",
    "lang": "en",
    "conversation_id": "1234567890123456789",
    "possibly_sensitive": false,
    "like_count": 5,
    "retweet_count": 1,
    "reply_count": 0,
    "quote_count": 0,
    "bookmark_count": 0,
    "is_quote_status": false,
    "entities": {
      "hashtags": [],
      "urls": [],
      "mentions": []
    }
  },
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 1,
      "remaining": 999
    }
  }
}

GET/v1/tweetsBasic Reads1 base + 1 per item#

Look up multiple tweets in one call by comma-separated IDs.

curl 'https://api.xfetch.io/v1/tweets?ids=1234567890123456789' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`ids`	query	`string`	required		Comma-separated IDs.

Response

{
  "data": [
    {
      "id": "1234567890123456789",
      "text": "xfetch ships /v1 today.",
      "author_id": "783214",
      "created_at": "2026-05-23T12:00:00.000Z",
      "lang": "en",
      "like_count": 5,
      "retweet_count": 1,
      "reply_count": 0,
      "quote_count": 0,
      "bookmark_count": 0,
      "is_quote_status": false,
      "entities": {
        "hashtags": [],
        "urls": [],
        "mentions": []
      }
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    }
  }
}

GET/v1/tweets/{id}/quotesBasic Reads1 base + 1 per item#

List quote tweets of a given tweet, most recent first.

curl 'https://api.xfetch.io/v1/tweets/1234567890123456789/quotes' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required
`next_token`	query	`string`	optional

Response

{
  "data": [
    {
      "id": "1234567890123456789",
      "text": "Quoting xfetch launch announcement.",
      "author_id": "783214",
      "created_at": "2026-05-23T12:00:00.000Z",
      "lang": "en",
      "like_count": 3,
      "retweet_count": 0,
      "reply_count": 0,
      "quote_count": 0,
      "bookmark_count": 0,
      "is_quote_status": true,
      "entities": {
        "hashtags": [],
        "urls": [],
        "mentions": []
      }
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    },
    "pagination": {
      "next_token": "tok_2"
    }
  }
}

GET/v1/tweets/{id}/retweetersBasic Reads1 base + 1 per item#

List users who retweeted a given tweet.

curl 'https://api.xfetch.io/v1/tweets/1234567890123456789/retweeters' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required
`next_token`	query	`string`	optional

Response

{
  "data": [
    {
      "id": "783214",
      "username": "xfetch",
      "name": "xfetch",
      "description": "Self-serve X/Twitter data API for anyone who needs the data.",
      "created_at": "2024-01-01T00:00:00.000Z",
      "verified": false,
      "protected": false,
      "profile_image_url": "https://example.com/avatar.png",
      "follower_count": 12000,
      "following_count": 18,
      "tweet_count": 240
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    },
    "pagination": {
      "next_token": "tok_2"
    }
  }
}

GET/v1/lists/{id}/tweetsBasic Reads1 base + 1 per item#

Read tweets from a public list.

curl 'https://api.xfetch.io/v1/lists/9999000099990000/tweets' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required
`next_token`	query	`string`	optional

Response

{
  "data": [
    {
      "id": "1234567890123456789",
      "text": "xfetch ships /v1 today.",
      "author_id": "783214",
      "created_at": "2026-05-23T12:00:00.000Z",
      "lang": "en",
      "like_count": 5,
      "retweet_count": 1,
      "reply_count": 0,
      "quote_count": 0,
      "bookmark_count": 0,
      "is_quote_status": false,
      "entities": {
        "hashtags": [],
        "urls": [],
        "mentions": []
      }
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    },
    "pagination": {
      "next_token": "tok_2"
    }
  }
}

GET/v1/lists/{id}/membersBasic Reads1 base + 1 per item#

List members of a public list.

curl 'https://api.xfetch.io/v1/lists/9999000099990000/members' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required
`next_token`	query	`string`	optional

Response

{
  "data": [
    {
      "id": "783214",
      "username": "xfetch",
      "name": "xfetch",
      "description": "Self-serve X/Twitter data API for anyone who needs the data.",
      "created_at": "2024-01-01T00:00:00.000Z",
      "verified": false,
      "protected": false,
      "profile_image_url": "https://example.com/avatar.png",
      "follower_count": 12000,
      "following_count": 18,
      "tweet_count": 240
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    },
    "pagination": {
      "next_token": "tok_2"
    }
  }
}

GET/v1/lists/{id}/subscribersBasic Reads1 base + 1 per item#

List subscribers of a public list.

curl 'https://api.xfetch.io/v1/lists/9999000099990000/subscribers' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required
`next_token`	query	`string`	optional

Response

{
  "data": [
    {
      "id": "783214",
      "username": "xfetch",
      "name": "xfetch",
      "description": "Self-serve X/Twitter data API for anyone who needs the data.",
      "created_at": "2024-01-01T00:00:00.000Z",
      "verified": false,
      "protected": false,
      "profile_image_url": "https://example.com/avatar.png",
      "follower_count": 12000,
      "following_count": 18,
      "tweet_count": 240
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    },
    "pagination": {
      "next_token": "tok_2"
    }
  }
}

GET/v1/communities/{id}Basic ReadsFlat 1 credit#

Look up one community by ID.

curl 'https://api.xfetch.io/v1/communities/1000200030004000' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required

Response

{
  "data": {
    "id": "1000200030004000",
    "name": "xfetch data workflows",
    "description": "People using the xfetch API for public data.",
    "member_count": 240
  },
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 1,
      "remaining": 999
    }
  }
}

GET/v1/communities/searchBasic Reads1 base + 1 per item#

Search communities matching a query.

curl 'https://api.xfetch.io/v1/communities/search?query=xfetch' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`query`	query	`string`	required
`next_token`	query	`string`	optional

Response

{
  "data": [
    {
      "id": "1000200030004000",
      "name": "xfetch data workflows",
      "description": "People using the xfetch API for public data.",
      "member_count": 240
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    },
    "pagination": {
      "next_token": "tok_2"
    }
  }
}

GET/v1/communities/{id}/membersBasic Reads1 base + 1 per item#

List members of a community.

curl 'https://api.xfetch.io/v1/communities/1000200030004000/members' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required
`next_token`	query	`string`	optional

Response

{
  "data": [
    {
      "id": "783214",
      "username": "xfetch",
      "name": "xfetch",
      "description": "Self-serve X/Twitter data API for anyone who needs the data.",
      "created_at": "2024-01-01T00:00:00.000Z",
      "verified": false,
      "protected": false,
      "profile_image_url": "https://example.com/avatar.png",
      "follower_count": 12000,
      "following_count": 18,
      "tweet_count": 240
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    },
    "pagination": {
      "next_token": "tok_2"
    }
  }
}

GET/v1/communities/{id}/moderatorsBasic Reads1 base + 1 per item#

List moderators of a community.

curl 'https://api.xfetch.io/v1/communities/1000200030004000/moderators' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required
`next_token`	query	`string`	optional

Response

{
  "data": [
    {
      "id": "783214",
      "username": "xfetch",
      "name": "xfetch",
      "description": "Self-serve X/Twitter data API for anyone who needs the data.",
      "created_at": "2024-01-01T00:00:00.000Z",
      "verified": false,
      "protected": false,
      "profile_image_url": "https://example.com/avatar.png",
      "follower_count": 12000,
      "following_count": 18,
      "tweet_count": 240
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    },
    "pagination": {
      "next_token": "tok_2"
    }
  }
}

Enriched Reads

GET/v1/users/{id}/followersEnriched Reads1 base + 1 per 50 items (varies by mode)#

List follower profile objects for enriched audience analysis.

curl 'https://api.xfetch.io/v1/users/783214/followers?mode=profiles' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required
`next_token`	query	`string`	optional
`mode`	query	`string`	optional	ids \| profiles
`limit`	query	`integer`	optional	default: 200	Supported only when mode=ids.

Response

{
  "data": [
    {
      "id": "783214",
      "username": "xfetch",
      "name": "xfetch",
      "description": "Self-serve X/Twitter data API for anyone who needs the data.",
      "created_at": "2024-01-01T00:00:00.000Z",
      "verified": false,
      "protected": false,
      "profile_image_url": "https://example.com/avatar.png",
      "follower_count": 12000,
      "following_count": 18,
      "tweet_count": 240
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    },
    "pagination": {
      "next_token": "tok_2"
    }
  }
}

GET/v1/users/{id}/followingEnriched Reads1 base + 1 per 50 items (varies by mode)#

List followed account profile objects for enriched audience analysis.

curl 'https://api.xfetch.io/v1/users/783214/following?mode=profiles' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required
`next_token`	query	`string`	optional
`mode`	query	`string`	optional	ids \| profiles
`limit`	query	`integer`	optional	default: 200	Supported only when mode=ids.

Response

{
  "data": [
    {
      "id": "783214",
      "username": "xfetch",
      "name": "xfetch",
      "description": "Self-serve X/Twitter data API for anyone who needs the data.",
      "created_at": "2024-01-01T00:00:00.000Z",
      "verified": false,
      "protected": false,
      "profile_image_url": "https://example.com/avatar.png",
      "follower_count": 12000,
      "following_count": 18,
      "tweet_count": 240
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    },
    "pagination": {
      "next_token": "tok_2"
    }
  }
}

GET/v1/tweets/{id}/articleEnriched ReadsFlat 1 credit#

Get a tweet's X long-form Article as a normalized, reading-ordered list of typed content blocks.

curl 'https://api.xfetch.io/v1/tweets/1234567890123456789/article' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required

Response

{
  "data": {
    "tweet_id": "1234567890123456789",
    "title": "How xfetch thinks about workflow APIs",
    "preview_text": "A short summary of the article.",
    "cover_image_url": "https://example.com/cover.jpg",
    "created_at": "2026-05-23T12:00:00.000Z",
    "content": [
      {
        "type": "heading_2",
        "text": "Why workflows"
      },
      {
        "type": "paragraph",
        "text": "Workflow endpoints replace several calls."
      },
      {
        "type": "image",
        "image_url": "https://example.com/figure.jpg",
        "width": 1200,
        "height": 675
      }
    ],
    "metrics": {
      "like_count": 120,
      "reply_count": 8,
      "quote_count": 4,
      "bookmark_count": 30,
      "view_count": 21000
    },
    "author": {
      "id": "783214",
      "username": "xfetch",
      "name": "xfetch",
      "description": "Self-serve X/Twitter data API for anyone who needs the data.",
      "verified": false,
      "protected": false,
      "profile_image_url": "https://example.com/avatar.png",
      "follower_count": 12000,
      "following_count": 18,
      "tweet_count": 240
    }
  },
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 1,
      "remaining": 999
    }
  }
}

GET/v1/search/recent/enrichedEnriched Reads1 base + 2 per item#

Search recent tweets and return matching tweets plus deduped authors; join via `tweet.author_id`.

curl 'https://api.xfetch.io/v1/search/recent/enriched?query=bitcoin%20min_faves%3A100%20lang%3Aen%20-filter%3Areplies' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`query`	query	`string`	required		Search text. Supports X-style operators: "quoted phrases", OR, () grouping, #hashtag, $cashtag, from:, lang:, since:/until: (YYYY-MM-DD), min_faves:, min_retweets:, filter:links, and - negation (e.g. -filter:replies).
`limit`	query	`integer`	optional	default: 20	Page size for search-backed results.
`next_token`	query	`string`	optional

Response

{
  "data": {
    "tweets": [
      {
        "id": "1234567890123456789",
        "text": "xfetch ships /v1 today.",
        "author_id": "783214",
        "created_at": "2026-05-23T12:00:00.000Z",
        "lang": "en",
        "conversation_id": "1234567890123456789",
        "possibly_sensitive": false,
        "like_count": 5,
        "retweet_count": 1,
        "reply_count": 0,
        "quote_count": 0,
        "bookmark_count": 0,
        "is_quote_status": false,
        "entities": {
          "hashtags": [],
          "urls": [],
          "mentions": []
        }
      }
    ],
    "authors": [
      {
        "id": "783214",
        "username": "xfetch",
        "name": "xfetch",
        "description": "Self-serve X/Twitter data API for anyone who needs the data.",
        "created_at": "2024-01-01T00:00:00.000Z",
        "verified": false,
        "protected": false,
        "profile_image_url": "https://example.com/avatar.png",
        "follower_count": 12000,
        "following_count": 18,
        "tweet_count": 240
      }
    ]
  },
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 3,
      "remaining": 997
    },
    "pagination": {
      "next_token": "tok_2"
    }
  }
}

GET/v1/communities/{id}/tweetsEnriched Reads1 base + 1 per item#

Read community tweets with relevance, recency, or likes-based sorting.

curl 'https://api.xfetch.io/v1/communities/1000200030004000/tweets' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required
`next_token`	query	`string`	optional
`sort`	query	`string`	optional	relevance \| recency \| likes
`time_filter`	query	`string`	optional	day \| week \| month \| year \| all	Only accepted when sort=likes.

Response

{
  "data": [
    {
      "id": "1234567890123456789",
      "text": "xfetch ships /v1 today.",
      "author_id": "783214",
      "created_at": "2026-05-23T12:00:00.000Z",
      "lang": "en",
      "like_count": 5,
      "retweet_count": 1,
      "reply_count": 0,
      "quote_count": 0,
      "bookmark_count": 0,
      "is_quote_status": false,
      "entities": {
        "hashtags": [],
        "urls": [],
        "mentions": []
      }
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    },
    "pagination": {
      "next_token": "tok_2"
    }
  }
}

Workflow APIs

GET/v1/tweets/{id}/conversationWorkflow APIs1 base + 1 per item#

Read the paginated reply thread under a tweet; the focal tweet itself is not included in `data`.

curl 'https://api.xfetch.io/v1/tweets/1234567890123456789/conversation' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required
`next_token`	query	`string`	optional

Response

{
  "data": [
    {
      "id": "1234567890123456789",
      "text": "Great to hear! Tell me more.",
      "author_id": "783214",
      "created_at": "2026-05-23T12:00:00.000Z",
      "lang": "en",
      "conversation_id": "1234567890123456789",
      "in_reply_to_user_id": "42",
      "possibly_sensitive": false,
      "like_count": 1,
      "retweet_count": 0,
      "reply_count": 0,
      "quote_count": 0,
      "bookmark_count": 0,
      "is_quote_status": false,
      "referenced_tweets": [
        {
          "type": "replied_to",
          "id": "1234567890123456789"
        }
      ],
      "entities": {
        "hashtags": [],
        "urls": [],
        "mentions": []
      }
    }
  ],
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    },
    "pagination": {
      "next_token": "tok_2"
    }
  }
}

GET/v1/tweets/{id}/threadWorkflow APIs1 base + 1 per item#

Reconstruct the root author's self-thread for a tweet, excluding other users' replies.

curl 'https://api.xfetch.io/v1/tweets/1234567890123456789/thread' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required

Response

{
  "data": {
    "conversation_id": "1234567890123456789",
    "author_id": "783214",
    "complete": true,
    "tweets": [
      {
        "id": "1234567890123456789",
        "text": "1/ Why xfetch ships workflow endpoints.",
        "author_id": "783214",
        "created_at": "2026-05-23T12:00:00.000Z",
        "lang": "en",
        "conversation_id": "1234567890123456789",
        "like_count": 12,
        "retweet_count": 2,
        "reply_count": 1,
        "quote_count": 0,
        "bookmark_count": 0,
        "is_quote_status": false,
        "entities": {
          "hashtags": [],
          "urls": [],
          "mentions": []
        }
      },
      {
        "id": "1234567890123456790",
        "text": "2/ Fewer calls, predictable billing.",
        "author_id": "783214",
        "created_at": "2026-05-23T12:01:00.000Z",
        "lang": "en",
        "conversation_id": "1234567890123456789",
        "like_count": 8,
        "retweet_count": 1,
        "reply_count": 0,
        "quote_count": 0,
        "bookmark_count": 0,
        "is_quote_status": false,
        "entities": {
          "hashtags": [],
          "urls": [],
          "mentions": []
        }
      }
    ]
  },
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 3,
      "remaining": 997
    }
  }
}

GET/v1/profiles/{id}Workflow APIs1 base + 1 per item#

Aggregate one user and their recent tweets in a single workflow call.

curl 'https://api.xfetch.io/v1/profiles/783214' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required

Response

{
  "data": {
    "user": {
      "id": "783214",
      "username": "xfetch",
      "name": "xfetch",
      "description": "Self-serve X/Twitter data API for anyone who needs the data.",
      "created_at": "2024-01-01T00:00:00.000Z",
      "verified": false,
      "protected": false,
      "profile_image_url": "https://example.com/avatar.png",
      "follower_count": 12000,
      "following_count": 18,
      "tweet_count": 240,
      "status": "active"
    },
    "recent_tweets": [
      {
        "id": "1234567890123456789",
        "text": "xfetch ships /v1 today.",
        "author_id": "783214",
        "created_at": "2026-05-23T12:00:00.000Z",
        "lang": "en",
        "conversation_id": "1234567890123456789",
        "possibly_sensitive": false,
        "like_count": 5,
        "retweet_count": 1,
        "reply_count": 0,
        "quote_count": 0,
        "bookmark_count": 0,
        "is_quote_status": false,
        "entities": {
          "hashtags": [],
          "urls": [],
          "mentions": []
        }
      }
    ]
  },
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    }
  }
}

GET/v1/profiles/by-username/{username}Workflow APIs1 base + 1 per item#

Aggregate one user (by username) and their recent tweets in a single workflow call.

curl 'https://api.xfetch.io/v1/profiles/by-username/xfetch' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`username`	path	`string`	required

Response

{
  "data": {
    "user": {
      "id": "783214",
      "username": "xfetch",
      "name": "xfetch",
      "description": "Self-serve X/Twitter data API for anyone who needs the data.",
      "created_at": "2024-01-01T00:00:00.000Z",
      "verified": false,
      "protected": false,
      "profile_image_url": "https://example.com/avatar.png",
      "follower_count": 12000,
      "following_count": 18,
      "tweet_count": 240,
      "status": "active"
    },
    "recent_tweets": [
      {
        "id": "1234567890123456789",
        "text": "xfetch ships /v1 today.",
        "author_id": "783214",
        "created_at": "2026-05-23T12:00:00.000Z",
        "lang": "en",
        "conversation_id": "1234567890123456789",
        "possibly_sensitive": false,
        "like_count": 5,
        "retweet_count": 1,
        "reply_count": 0,
        "quote_count": 0,
        "bookmark_count": 0,
        "is_quote_status": false,
        "entities": {
          "hashtags": [],
          "urls": [],
          "mentions": []
        }
      }
    ]
  },
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 2,
      "remaining": 998
    }
  }
}

GET/v1/tweets/{id}/contextWorkflow APIs1 base + 1 per item#

Aggregate one tweet's author, quotes, and retweeters in a single workflow call.

curl 'https://api.xfetch.io/v1/tweets/1234567890123456789/context' \
  -H 'Authorization: Bearer $XFETCH_API_KEY'

Name	In	Type	Required	Default / Enum	Description
`id`	path	`string`	required

Response

{
  "data": {
    "tweet": {
      "id": "1234567890123456789",
      "text": "xfetch is live.",
      "author_id": "783214",
      "created_at": "2026-05-23T12:00:00.000Z",
      "lang": "en",
      "conversation_id": "1234567890123456789",
      "possibly_sensitive": false,
      "like_count": 42,
      "retweet_count": 7,
      "reply_count": 3,
      "quote_count": 1,
      "bookmark_count": 0,
      "is_quote_status": false,
      "entities": {
        "hashtags": [],
        "urls": [],
        "mentions": []
      }
    },
    "author": {
      "id": "783214",
      "username": "xfetch",
      "name": "xfetch",
      "description": "Self-serve X/Twitter data API for anyone who needs the data.",
      "created_at": "2024-01-01T00:00:00.000Z",
      "verified": false,
      "protected": false,
      "profile_image_url": "https://example.com/avatar.png",
      "follower_count": 12000,
      "following_count": 18,
      "tweet_count": 240
    },
    "quotes": [],
    "retweeters": []
  },
  "meta": {
    "request_id": "req_01HXFETCHEXAMPLE",
    "credits": {
      "charged": 1,
      "remaining": 999
    }
  }
}

/2 compatibility

/2 mirrors the /v1 Basic Reads layer with official-style paths and query names for teams migrating familiar code. For full /2 details see /docs/x-api-compatible.

Capability	/v1 endpoint	/2 endpoint
Recent search	`GET /v1/search/recent`	`GET /2/tweets/search/recent`
User by username	`GET /v1/users/by-username/:username`	`GET /2/users/by/username/:username`
User by id	`GET /v1/users/:id`	`GET /2/users/:id`
Users by ids	`GET /v1/users?ids=...`	`GET /2/users?ids=...`
User tweets	`GET /v1/users/:id/tweets`	`GET /2/users/:id/tweets`
Followers	`GET /v1/users/:id/followers?mode=ids`	`GET /2/users/:id/followers`
Following	`GET /v1/users/:id/following?mode=ids`	`GET /2/users/:id/following`
Tweet by id	`GET /v1/tweets/:id`	`GET /2/tweets/:id`
Tweets by ids	`GET /v1/tweets?ids=...`	`GET /2/tweets?ids=...`
Quote tweets	`GET /v1/tweets/:id/quotes`	`GET /2/tweets/:id/quote_tweets`
Retweeters	`GET /v1/tweets/:id/retweeters`	`GET /2/tweets/:id/retweeted_by`
List tweets	`GET /v1/lists/:id/tweets`	`GET /2/lists/:id/tweets`
List members	`GET /v1/lists/:id/members`	`GET /2/lists/:id/members`
List subscribers/followers	`GET /v1/lists/:id/subscribers`	`GET /2/lists/:id/followers`

Run a request on your own key.

Sign in with Google to mint a key and call any endpoint above from the dashboard playground. New accounts receive 1,000 credits; failed validation, auth failures, insufficient credits, rate limits, and service-side failures are not charged.