---
title: "Twitter/X User Tweets API"
method: GET
path: "/v1/twitter/user-tweets"
tags: ["Twitter / X"]
---

# Twitter/X User Tweets API

`GET /v1/twitter/user-tweets`

## Request

- Base URL: `https://api.captapi.com`
- URL: `https://api.captapi.com/v1/twitter/user-tweets`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Most popular public tweets from a Twitter/X profile (~100 cap) — not chronological.

Pass a profile URL or @handle and get the tweets Twitter's public timeline embed exposes as clean JSON. Important: this is not a chronological or latest feed — Twitter publicly returns on the order of ~100 of the account's most popular posts. Do not use this endpoint to detect new tweets. There is no cursor: the envelope names the window (requested / listingHits / hasMore / truncatedReason=popular-window). hasMore means raise limit, not pass a cursor. Each tweet uses the shared contract: ISO-8601 publishedAt, author, engagement{likes,replies,retweets,quotes} — views and bookmarks are omitted on this surface (syndication never exposes them; community-tweets / tweet-details do via GraphQL), isReply / isRetweet / isQuote, conversationId, source when present, hashtags[] and media[]. Flat 2 credits per call. Pass cache=true to serve from the 24h shared cache (0 credits on hit); default is always fresh. Empty verdicts are honest 200s at 0 credits: truncatedReason no-tweets (profile reports 0 tweets) or embed-empty (the embed renders the account without posts — deterministic, retrying does not change it). When the embed does not answer at all (transport miss, or the 45s ceiling), the last answer we fetched for that handle in the previous 26h is replayed as stale:true / cached:true with fetchedAt (scrape time) and servedAt, plus a note, at 0 credits — the popular window moves slowly, so yesterday's snapshot beats a retryable 502. Only a handle with no snapshot gets the 502/503.

Docs: https://captapi.com/apis/twitter-user-tweets

## Query parameters

- `url` string, required
- `limit` integer
- `cache` boolean

## Response `200`

Success. The data object for this endpoint.

- object
  - `success` unknown, required
  - `data` object, required
    - `handle` string: Account handle.
    - `totalReturned` integer: Number of items returned in this response.
    - `tweets` object[]
      - `platform` string: Platform identifier for this response (matches the endpoint's platform).
      - `url` string: Canonical URL of the item.
      - `id` string: Id of this tweets item.
      - `text` string: Text content.
      - `lang` string: Language code of the content.
      - `publishedAt` string: Tweet publish time as ISO-8601 UTC (e.g. 2022-04-28T00:56:58.000Z). Not Twitter's raw created_at string.
      - `author` object: Author name or handle.
        - `id` string: Id of this tweets item.
        - `username` string
        - `displayName` string
        - `url` string: Canonical URL of the item.
        - `followers` integer
        - `verified` boolean
        - `profileImage` string
      - `isReply` boolean: Whether the tweet is a reply.
      - `isRetweet` boolean: Whether the tweet is a retweet.
      - `possiblySensitive` boolean: Possibly sensitive. Example: false.
      - `conversationId` string: Thread root id (conversation_id_str) for grouping replies.
      - `engagement` object: Engagement metrics for the item.
        - `views` unknown
        - `likes` integer
        - `replies` integer
        - `retweets` integer
        - `quotes` integer
        - `bookmarks` unknown
      - `hashtags` unknown[]: Hashtag texts without #. Always an array (empty when the tweet has none).
        - unknown
      - `media` unknown[]: Media image/video preview URLs when present. Always an array (empty when none).
        - unknown

## Other responses

- `400`: Bad request: wrong platform URL, unknown endpoint, or an invalid parameter value. Not billed.
- `401`: Missing, invalid or revoked API key. Not billed.
- `402`: Not enough credits for this request. Not billed.
- `404`: The resource does not exist or is not public. Not billed.
- `422`: A required parameter is missing or has the wrong type. Not billed.
- `429`: Rate limit reached. Wait for Retry-After seconds. Not billed.
- `502`: The platform could not be reached or returned nothing usable. Retryable, not billed. 503 and 504 use the same envelope.

---

[API](https://skmtc.dev/captapi/apis/captapi-api.md) · [All operations](https://skmtc.dev/captapi/apis/captapi-api/llms.txt) · [OpenAPI document](https://skmtc.dev/captapi/apis/captapi-api/revisions/c9b9ac5ff1bd?raw)