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.

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.