# xfetch Agent Context

Last updated: 2026-07-13

xfetch provides current public X/Twitter data over REST or hosted MCP, plus real-time account monitors for Discord and generic signed webhooks. Data access supports search and social listening, AI/LLM pipelines, profile and account intelligence, audience graph analysis, tweet context analysis, and trend or market research.

Production is live at `https://xfetch.io`; the customer API is served from `https://api.xfetch.io`.

## API Layers

- Start new integrations with `/v1`; it is the recommended product API.
- `Basic Reads`: direct read endpoints for familiar search, user, tweet, graph, list, community, and trend data.
- `Enriched Reads`: read-shaped endpoints that add normalized objects or richer response modes around a core resource.
- `Workflow APIs`: aggregated endpoints for jobs such as profile intelligence, tweet context analysis, and conversation review.
- `/2` compatibility: Basic Reads migration layer with official-style paths, query names, and response envelopes where supported. xfetch credit metadata is returned in response headers.
- `/v1` uses xfetch-owned parameters. Paginated endpoints use opaque `next_token`; recent search, trends, and graph `mode=ids` expose endpoint-specific `limit`; continuation-only endpoints do not expose `limit`.

## Public Acquisition Pages

- `/`: homepage for `Twitter data API` intent; explains read workflows, `/v1` workflow APIs, focused `/2` compatibility, credits, AI/agent data shape, and account monitoring.
- `/twitter-account-monitor`: dedicated `Twitter account monitor` page for dashboard-configured account monitors, Discord incoming webhook delivery, generic signed webhooks, trial slots, and per-account pricing.
- `/use-cases/twitter-data-api-for-ai-agents`: AI/agent pipeline page for normalized JSON, deduped authors, enriched search, tweet context, `/openapi.json`, and `/llms.txt`.
- `/use-cases/bitcoin-social-intelligence`: vertical example for Bitcoin social intelligence using enriched search, tweet context, account monitors, lists, communities, and profile reads.

## Authentication

Send customer API keys as Bearer tokens:

```http
Authorization: Bearer <api_key>
```

## Credits

- Free signup grants 1,000 credits for new users.
- Single-object lookups cost 1 credit.
- Collection endpoints cost 1 base credit plus 1 credit per returned primary item.
- Dedicated `/v1` workflow keys use value-tier rules: `search.enriched` is 1 base + 2 credits per returned tweet, `profile.lookup` is 1 base + 1 credit per recent tweet, and `tweet.context` is 1 base + 1 credit per quote or retweeter. Graph IDs cost 1 base + 1 credit per 50 IDs.
- Failed validation, auth failures, insufficient credits, rate limits, service-side failures, and internal failures do not charge users.
- `/v1` returns credit metadata in `meta.credits`.
- `/2` returns credit metadata in response headers.
- On `402 insufficient_credits`, the error body includes a `help_url` to add credits or choose a plan (both `/v1` and `/2`); follow it to restore access.

## Hosted MCP For AI Agents

- xfetch offers a Hosted remote MCP server at `https://api.xfetch.io/mcp` for remote-MCP-compatible clients.
- Authentication uses `Authorization: Bearer <xfetch_api_key>` from the dashboard.
- MCP tools consume normal endpoint credits, return provider-neutral public errors, and follow the same no-charge-on-failure rules as `/v1`.
- First tools: `search_x_posts`, `lookup_x_profile`, `get_x_tweet_context`, `get_x_user_timeline`, `get_x_followers`, and `get_x_following`.
- MCP is an agent tool surface; `/openapi.json` remains the API contract.
- MCP is read-only. Posting, liking, reposting, following, DMs, monitor setup, and billing tools are outside the MCP tool surface.

## Pricing And Plans

- Machine-readable pricing is available at `/pricing.md`.
- Free and PAYG credits do not expire.
- Subscription credits expire at period end and do not roll over.
- Public rate limits by access level: Free 60 req/min, PAYG 300 req/min, Starter 600 req/min, Growth 900 req/min, Pro 1,500 req/min, Scale 2,400 req/min.

## Account Monitoring

- Monitor configuration is dashboard-only; there is no public monitor configuration API.
- Account monitoring: Free and PAYG include one 10-day trial monitor slot; monthly plans include permanent monitor slots (Starter 2, Growth 5, Pro 10, Scale 25). The extra-account rate is $3 per account / month. Each slot watches one account and can deliver to one Discord channel and one generic webhook.
- Users can start from suggested accounts or resolve an exact public `@handle` in the dashboard add flow. To deliver the same account to multiple Discord channels, create multiple monitor slots.
- Monitor delivery channels support generic signed webhooks and Discord incoming webhooks. Deliveries retry on failure and never spend API credits.

## Basic Reads Mapping: `/v1` to `/2`

The `/v1` Basic layer covers the supported `/2` compatibility capabilities. Naming differs where `/v1` uses product-owned paths or query names.

- Recent search: GET /v1/search/recent maps to GET /2/tweets/search/recent. Use /v1 for xfetch-owned limit and pagination names; use /2 for migration-compatible query names.
- User by username: GET /v1/users/by-username/:username maps to GET /2/users/by/username/:username. Both layers support direct username lookup with layer-specific path naming.
- User by id: GET /v1/users/:id maps to GET /2/users/:id. Both layers support direct user lookup by ID.
- Users by ids: GET /v1/users?ids=... maps to GET /2/users?ids=.... Both layers support batch user lookup with comma-separated IDs.
- User tweets: GET /v1/users/:id/tweets maps to GET /2/users/:id/tweets. Use /v1 for normalized tweet fields and xfetch pagination names.
- Followers: GET /v1/users/:id/followers?mode=ids maps to GET /2/users/:id/followers. The Basic /v1 mapping recommends IDs mode for high-volume graph reads.
- Following: GET /v1/users/:id/following?mode=ids maps to GET /2/users/:id/following. The Basic /v1 mapping recommends IDs mode for high-volume graph reads.
- Tweet by id: GET /v1/tweets/:id maps to GET /2/tweets/:id. Both layers support direct tweet lookup by ID.
- Tweets by ids: GET /v1/tweets?ids=... maps to GET /2/tweets?ids=.... Both layers support batch tweet lookup with comma-separated IDs.
- Quote tweets: GET /v1/tweets/:id/quotes maps to GET /2/tweets/:id/quote_tweets. Use /v1 for product naming; /2 keeps the official-compatible path.
- Retweeters: GET /v1/tweets/:id/retweeters maps to GET /2/tweets/:id/retweeted_by. Both layers expose users who retweeted the tweet with layer-specific names.
- List tweets: GET /v1/lists/:id/tweets maps to GET /2/lists/:id/tweets. Both layers support reading tweets from a list.
- List members: GET /v1/lists/:id/members maps to GET /2/lists/:id/members. Both layers support reading list members.
- List subscribers/followers: GET /v1/lists/:id/subscribers maps to GET /2/lists/:id/followers. The /v1 path uses product naming while /2 keeps the official-compatible followers path.

## Enriched Reads

- GET /v1/search/recent/enriched
- GET /v1/users/:id/followers?mode=profiles
- GET /v1/users/:id/following?mode=profiles
- GET /v1/communities/:id/tweets
- GET /v1/tweets/:id/article

## Workflow APIs

- GET /v1/profiles/:id
- GET /v1/profiles/by-username/:username
- GET /v1/tweets/:id/context
- GET /v1/tweets/:id/conversation
- GET /v1/tweets/:id/thread

## Public `/v1` Endpoints

- GET /v1/trends — see /docs/api-reference#v1-trends
- GET /v1/search/recent — see /docs/api-reference#v1-search-recent
- GET /v1/users/:id — see /docs/api-reference#v1-users-id
- GET /v1/users/by-username/:username — see /docs/api-reference#v1-users-by-username-username
- GET /v1/users?ids=... — see /docs/api-reference#v1-users-ids
- GET /v1/users/:id/tweets — see /docs/api-reference#v1-users-id-tweets
- GET /v1/users/:id/tweets/replies — see /docs/api-reference#v1-users-id-tweets-replies
- GET /v1/users/:id/media — see /docs/api-reference#v1-users-id-media
- GET /v1/users/:id/followers?mode=ids|profiles — see /docs/api-reference#v1-users-id-followers-mode-ids-profiles
- GET /v1/users/:id/verified-followers — see /docs/api-reference#v1-users-id-verified-followers
- GET /v1/users/:id/following?mode=ids|profiles — see /docs/api-reference#v1-users-id-following-mode-ids-profiles
- GET /v1/users/relationship?source=...&target=... — see /docs/api-reference#v1-users-relationship-source-target
- GET /v1/tweets/:id — see /docs/api-reference#v1-tweets-id
- GET /v1/tweets?ids=... — see /docs/api-reference#v1-tweets-ids
- GET /v1/tweets/:id/quotes — see /docs/api-reference#v1-tweets-id-quotes
- GET /v1/tweets/:id/retweeters — see /docs/api-reference#v1-tweets-id-retweeters
- GET /v1/tweets/:id/conversation — see /docs/api-reference#v1-tweets-id-conversation
- GET /v1/tweets/:id/thread — see /docs/api-reference#v1-tweets-id-thread
- GET /v1/tweets/:id/article — see /docs/api-reference#v1-tweets-id-article
- GET /v1/lists/:id/tweets — see /docs/api-reference#v1-lists-id-tweets
- GET /v1/lists/:id/members — see /docs/api-reference#v1-lists-id-members
- GET /v1/lists/:id/subscribers — see /docs/api-reference#v1-lists-id-subscribers
- GET /v1/communities/:id — see /docs/api-reference#v1-communities-id
- GET /v1/communities/search — see /docs/api-reference#v1-communities-search
- GET /v1/search/recent/enriched — see /docs/api-reference#v1-search-recent-enriched
- GET /v1/profiles/:id — see /docs/api-reference#v1-profiles-id
- GET /v1/profiles/by-username/:username — see /docs/api-reference#v1-profiles-by-username-username
- GET /v1/tweets/:id/context — see /docs/api-reference#v1-tweets-id-context
- GET /v1/communities/:id/tweets — see /docs/api-reference#v1-communities-id-tweets
- GET /v1/communities/:id/members — see /docs/api-reference#v1-communities-id-members
- GET /v1/communities/:id/moderators — see /docs/api-reference#v1-communities-id-moderators

## Public `/2` Endpoints

- GET /2/tweets/search/recent
- GET /2/users/by/username/:username
- GET /2/users/:id/tweets
- GET /2/users/:id/followers
- GET /2/users/:id/following
- GET /2/users/:id
- GET /2/users?ids=...
- GET /2/tweets/:id/retweeted_by
- GET /2/tweets/:id/quote_tweets
- GET /2/tweets/:id
- GET /2/tweets?ids=...
- GET /2/lists/:id/tweets
- GET /2/lists/:id/members
- GET /2/lists/:id/followers

## `/v1` Item Shapes

User object fields: `id`, `username`, `name`, `description`, `location` (optional), `created_at` (ISO 8601), `verified` (boolean), `protected` (boolean), `profile_image_url`, `follower_count`, `following_count`, `tweet_count`, `media_count` (optional).

Dedicated user lookup and profile user blocks add `status`: `active`, `suspended`, `deactivated`, `unavailable`, or `not_found`. All five statuses are billed as successful lookups; `not_found` data echoes the requested `id`/`username`.

Non-active user lookup data may be sparse: `{ id?, username?, status }`.

Tweet object fields: `id`, `text`, `author_id`, `created_at` (ISO 8601), `lang`, `like_count`, `retweet_count`, `reply_count`, `quote_count`, `bookmark_count`, `is_quote_status` (boolean), `quoted_tweet_id` (optional), `entities` (`{ hashtags: string[], urls: string[], mentions: string[] }`), `media` (optional array of `{ type, url }` — video variant URLs and bitrates are intentionally not exposed).

Tweet context (`/v1/tweets/:id/context`) returns: `{ tweet, author, quotes, retweeters }`.

Enriched search (`/v1/search/recent/enriched`) returns `{ tweets, authors }`. `authors` is deduplicated by `id`, so its length is the number of unique authors on the page and may be smaller than `tweets.length`; join with `tweet.author_id`.

Recent-search `query` (`/v1/search/recent` and `/v1/search/recent/enriched`) 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`). Broad keyword queries return a high-volume recency stream; combine `min_faves:`/`lang:`/`-filter:replies` to get a research-grade signal stream.

Trends (`/v1/trends`) returns ranked trends for a WOEID (default `1` = worldwide).

Conversation (`/v1/tweets/:id/conversation`) returns the paginated reply thread. The focal tweet itself is **not** included in `data`; fetch it separately via `/v1/tweets/:id` if you need both. Pages may contain descendant replies (replies of replies) alongside direct replies.

Graph endpoints (`/v1/users/:id/followers`, `/v1/users/:id/following`) support `mode=ids` (returns `{ id }` only) or `mode=profiles` (returns full enriched user objects, default).

Graph `mode=ids` returns `{ id }` objects and supports `limit` up to 5000 for large paginated graph reads.

## Examples

```http
GET /v1/search/recent/enriched?query=bitcoin%20min_faves%3A100%20lang%3Aen%20-filter%3Areplies
```

```http
GET /v1/profiles/by-username/:username
```

```http
GET /v1/tweets/:id/context
```

```http
GET /v1/communities/:id/tweets
```

```http
GET /2/tweets/search/recent?query=xfetch&max_results=20
```

## Pagination

- `/v1` paginated endpoints use `next_token`.
- `/v1` exposes `limit` only where page size can be honored without dropping items: recent search (default 20, max 20), trends (default 20, max 100), and graph `mode=ids` (default 200, max 5000).
- `/2` paginated endpoints use official-compatible pagination query names where supported.
- Public pagination tokens are opaque. Do not parse or persist assumptions about token internals.

## Public Safety Boundaries

- xfetch supports public read workflows and dashboard-configured account monitoring in the current product scope.
- Account monitoring is dashboard-configured: Free and PAYG get one 10-day trial monitor slot, monthly plans include permanent slots, and the extra-account rate is $3 / account / month. Deliveries go to Discord incoming webhooks, generic signed webhooks, or both.
- There are no write actions such as posting, liking, reposting, following, or DMs.
- Public docs, API responses, playground output, and agent context should describe xfetch capabilities, not internal implementation details.

## Links

- /llms-full.txt - Full agent-readable xfetch context
- /openapi.json - OpenAPI 3.x public API contract
- /pricing.md - Machine-readable pricing and plan limits
- /docs - Human-readable docs
- /docs/api-reference - API reference
- /docs/mcp - Hosted remote MCP setup for AI agents
- /pricing - API credits and account-monitor pricing
- /twitter-account-monitor - Twitter account monitor explainer
- /use-cases/twitter-data-api-for-ai-agents - Twitter data API for AI agents
- /use-cases/bitcoin-social-intelligence - Bitcoin social intelligence use case
- /legal/terms - Terms
- /legal/privacy - Privacy
- /legal/refund - Refund policy