# X User Tweets Timeline

> X User Tweets Timeline is a paid API for AI agents from social.duoleads.com, paid per call via x402, $0.02/call, status unknown (last checked 2026-10-29).

Retrieves the latest public tweets from a specific X (Twitter) account by handle or profile URL, newest first, with engagement metrics and pagination.

## Facts

- Endpoint: GET https://social.duoleads.com/v1/x/posts?utm_source=zero.xyz
- Price: $0.02/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-29
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/x-user-tweets-timeline-21cfbf2c
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_PMg_WfEIzZcHc9nZUkn8k

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 x-user-tweets-timeline-21cfbf2c
```

Example prompt: Pull the latest tweets from @sama on X — I want to see the text, likes, retweets, and views for each post, starting with the newest.

## When to prefer this

Choose this endpoint when you need the full tweet timeline of a specific known X account — including text, author metadata, and engagement metrics — with pagination support. Prefer it over a social search endpoint when you already know the account handle and want a chronological feed rather than keyword-matched results. It is the right tool for brand monitoring, influencer auditing, or tracking what a specific user has been posting over time.

## Known failure modes

- Invalid or nonexistent handle returns a not-found response at no charge
- Malformed x.com URL or bad cursor value is treated as bad input and not charged
- Private or suspended accounts return no results
- Rate limits or upstream X API unavailability may cause temporary failures
- Empty timeline if account has no public tweets

## How this service works

X User Tweets Timeline: the latest public tweets of one X (Twitter) account by handle or x.com URL, newest first. Per tweet the text, author handle and name, verification, followers, likes, replies, retweets, views, language, reply or quote parent, time and URL in the shared social schema; next_cursor gives the next page. Bad input is free; not found or no match is not charged.

## Output

Returns a JSON object with an array of tweet items sorted newest first. Each tweet includes its ID, URL, full text, language, tweet type, author details (handle, display name, verification status, follower count), engagement metrics (likes, views, replies, reposts), platform, optional parent tweet ID for replies/quotes, timestamp, and media URLs. Also includes as_of timestamp, the original query parameters, a next_cursor for pagination, a request_id, and a disclaimer about data provenance.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "handle"
     ],
     "properties": {
      "cursor": {
       "type": "string",
       "maxLength": 512,
       "description": "next_cursor of the previous page."
      },
      "handle": {
       "type": "string",
       "maxLength": 200,
       "description": "An X handle (with or without @) or an x.com profile URL."
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object"
    }
   }
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "as_of": "2026-10-15T12:00:00.000Z",
  "items": [
   {
    "id": "1910000000000000001",
    "url": "https://x.com/synth_alpha/status/1910000000000000001",
    "lang": "en",
    "text": "Trying the synthwidget beta today, the dark mode is great",
    "type": "post",
    "author": {
     "handle": "synth_alpha",
     "verified": true,
     "followers": 1234,
     "display_name": "Synthetic Alpha"
    },
    "metrics": {
     "likes": 11,
     "views": 780,
     "replies": 4,
     "reposts": 2
    },
    "platform": "x",
    "parent_id": "1910000000000000901",
    "created_at": "2026-10-01T18:50:27.000Z",
    "media_urls": []
   },
   {
    "id": "1910000000000000002",
    "url": "https://x.com/synth_beta/status/1910000000000000002",
    "lang": "en",
    "text": "synthwidget support never answered my ticket",
    "type": "post",
    "author": {
     "handle": "synth_beta",
     "verified": false,
     "followers": 88,
     "display_name": "Synthetic Beta"
    },
    "metrics": {
     "likes": 0,
     "views": 45,
     "replies": 1,
     "reposts": 0
    },
    "platform": "x",
    "parent_id": "1910000000000000001",
    "created_at": "2026-10-02T09:00:00.000Z",
    "media_urls": []
   }
  ],
  "query": {
   "cursor": null,
   "handle": "synthbrand"
  },
  "source": "public data via third-party provider; not affiliated with the platform",
  "complete": true,
  "platform": "x",
  "disclaimer": "Public data via third-party providers; not affiliated with or endorsed by any platform. Do not use to profile, target or train AI on individuals.",
  "request_id": "01KEXAMPLE0000000000000000",
  "next_cursor": "synthcursor_posts_2"
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/x-user-tweets-timeline-21cfbf2c/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from social.duoleads.com](https://www.zero.xyz/host/social.duoleads.com/llms.txt)