# Twitter/X API Wrapper — Search, Lookup & Timeline

> Twitter/X API Wrapper — Search, Lookup & Timeline is a paid API for AI agents from x402.agentutility.ai, paid per call via x402, $0.01/call, status unknown (last checked 2026-09-13).

Read-only Twitter/X API v2 wrapper supporting recent tweet search, tweet ID lookup, single/bulk user profile lookup, and user timeline retrieval.

## Facts

- Endpoint: POST https://x402.agentutility.ai/twitter-x-api
- Price: $0.01/call
- Payment: x402
- Status: unknown
- Last checked: 2026-09-13
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/twitter-x-api-wrapper-search-lookup-timeline-272fc399
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_hMhC4ZgcPB2giQSZXa-PM

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability twitter-x-api-wrapper-search-lookup-timeline-272fc399 -d '<json body>'
```

Example prompt: Search Twitter for recent tweets about 'AI agents' and show me the top results, then also pull up the profile and recent tweets for the user @elonmusk.

## When to prefer this

Choose this endpoint when you need read-only access to public Twitter/X data — including tweet search, profile lookups, or timeline retrieval — without setting up your own X API credentials. Especially useful for agents that need social data on demand, paid per-call via USDC with no API key management. Prefer over direct X API integration when running as an autonomous agent with x402 micropayment support.

## Known failure modes

- Invalid or missing bearer token returns authentication error
- Username not found returns 404 or empty user object
- Tweet IDs that are deleted or private return not-found errors
- Search query returns empty results if no recent matching tweets
- Rate limits on the underlying X API v2 may cause 429 errors
- Bulk user lookup exceeding maximum batch size returns validation error

## How this service works

Twitter X API / X API v2 wrapper / tweet search, tweet lookup, username lookup, bulk users lookup, and user timeline fetch / social data API. Read-only endpoint with mode='search' for recent public posts, mode='tweets' for tweet IDs, mode='user' for one public profile, mode='users' for bulk profile lookup, or mode='user_tweets' for recent public posts from one username. Uses X_BEARER_TOKEN or TWITTER_BEARER_TOKEN. No posting, replying, liking, following, DM access, or account mutation.

## Output

Returns structured JSON containing tweet text, tweet IDs, author info, timestamps, and engagement metadata for search results; or user profile fields (username, display name, bio, follower/following counts, verified status) for user lookups; or a list of recent public posts for timeline requests.

## Request schema (JSON Schema)

```json
{
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "type": "object",
 "properties": {
  "input": {
   "type": "object",
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "type": "string",
     "enum": [
      "POST"
     ]
    },
    "bodyType": {
     "type": "string",
     "enum": [
      "json",
      "form-data",
      "text"
     ]
    },
    "body": {
     "properties": {
      "mode": {
       "type": "string",
       "enum": [
        "search",
        "user",
        "tweets",
        "users",
        "user_tweets"
       ],
       "description": "Lookup mode. Defaults to 'search' unless username or IDs are supplied."
      },
      "query": {
       "type": "string",
       "description": "Recent-search query for mode='search'."
      },
      "username": {
       "type": "string",
       "description": "Handle for mode='user' or mode='user_tweets', with or without @."
      },
      "usernames": {
       "type": "array",
       "items": {
        "type": "string"
       },
       "description": "Handles for mode='users'. Up to 100."
      },
      "tweet_ids": {
       "type": "array",
       "items": {
        "type": "string"
       },
       "description": "Tweet IDs for mode='tweets'. Up to 100."
      },
      "user_ids": {
       "type": "array",
       "items": {
        "type": "string"
       },
       "description": "User IDs for mode='users'. Up to 100."
      },
      "ids": {
       "type": "array",
       "items": {
        "type": "string"
       },
       "description": "Alias for tweet_ids in mode='tweets' or user_ids in mode='users'."
      },
      "max_results": {
       "type": "number",
       "description": "Search or user timeline result count. Search clamps to 10-50; user_tweets clamps to 5-50."
      },
      "language": {
       "type": "string",
       "description": "Optional two-letter language filter for search."
      },
      "pagination_token": {
       "type": "string",
       "description": "Optional X pagination token for mode='user_tweets'."
      },
      "include_retweets": {
       "type": "boolean",
       "description": "For mode='user_tweets', include retweets when true. Defaults false."
      }
     }
    }
   },
   "required": [
    "type",
    "method",
    "bodyType",
    "body"
   ],
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "properties": {
    "type": {
     "type": "string"
    },
    "example": 
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "mode": "search",
  "source": "X API v2 recent search",
  "result_count": 10
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/twitter-x-api-wrapper-search-lookup-timeline-272fc399/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from x402.agentutility.ai](https://www.zero.xyz/host/x402.agentutility.ai/llms.txt)