---
title: "Posts"
description: "List an X account's recent posts."
---

```http
GET | POST /v1/x/posts
```

Send parameters as a query string with `GET`, or as a JSON body with `POST`. Both are equivalent.

## What to Pass

| Pass | Reads | Notes |
|---|---|---|
| `username` or `userId` | The account's recent posts | `userId` saves a lookup |

Pass one source per call. Every identifier also takes the page URL.

## Which list you get

Logged-out X serves accounts one of two lists, and the page tells you which in `ext.order`:

- `latest`: the account's posts, newest first, about 20 per page with a `cursor` for the next page.
- `popular`: for some accounts X serves their most-liked posts instead, about 100 of them in one page, in no date order and with no `cursor`.

The account's pinned post comes first on the first page, marked `pinned: true`, and does not repeat on later pages. X decides the page size, so `limit` is a hint only.

## Parameters

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `cursor` | string |  | Opaque cursor from the previous page's `cursor`. Pass it alone for the next page. |
| `limit` | integer 1–100 |  | Items per page, 1–100 — a hint only: X decides the page size (about 20, or ~100 for the most-liked list). |
| `userId` | string |  | Numeric user id. Pass it instead of a username to save the lookup. |
| `username` | string |  | @handle (with or without @), or the profile URL. |

## Request

```bash tab="cURL"
curl "https://gateway.apinoa.com/v1/x/posts?username=nasa&limit=5" \
  -H "x-api-key: $APINOA_API_KEY"
```

```js tab="JavaScript"
const params = new URLSearchParams({ username: "nasa", limit: "5" });
const res = await fetch(`https://gateway.apinoa.com/v1/x/posts?${params}`, {
  headers: { "x-api-key": process.env.APINOA_API_KEY },
});
const { success, data, error } = await res.json();
```

```python tab="Python"
import os

import requests

res = requests.get(
    "https://gateway.apinoa.com/v1/x/posts",
    params={"username": "nasa", "limit": "5"},
    headers={"x-api-key": os.environ["APINOA_API_KEY"]},
)
body = res.json()
```

## Response

Returns [`Page`](/docs/api-reference/sns/response-schema#page) of [`Post`](/docs/api-reference/sns/response-schema#post) in `data`. A real response, shortened: arrays keep their first entries and long text is cut.

```json
{
  "success": true,
  "data": {
    "platform": "x",
    "items": [
      {
        "platform": "x",
        "id": "2113776971603689874",
        "url": "https://x.com/NASA/status/2113776971603689874",
        "author": {
          "platform": "x",
          "id": "11348282",
          "handle": "NASA",
          "displayName": "NASA",
          "url": "https://x.com/NASA",
          "avatarUrl": "https://pbs.twimg.com/profile_images/1321163587679784960/0ZxKlEKB.jpg",
          "verified": true,
          "counts": {
            "followers": 92311241,
            "following": 115,
            "posts": 74453
          },
          "ext": {
            "blueVerified": true,
            "verifiedType": "Government"
          }
        },
        "text": "We are not slowing down. 🚀\n\nOur Artemis III mission will send four astronauts to low Earth orbit next year to test crit…",
        "createdAt": "2026-10-23T23:37:56.000Z",
        "lang": "en",
        "media": [
          {
            "type": "video",
            "url": "https://video.twimg.com/amplify_video/2113776813121941504/vid/avc1/1920x1080/oa29OYgVBG7qAyEB.mp4?tag=16",
            "thumbnailUrl": "https://pbs.twimg.com/media/HVWk812WIAAg_hz.jpg?name=orig",
            "width": 3840,
            "height": 2160,
            "durationSec": 59.893,
            "variants": [
              {
                "url": "https://video.twimg.com/amplify_video/2113776813121941504/pl/Sws2JLpHl8xdzMyH.m3u8?tag=16&v=ab6",
                "contentType": "application/x-mpegURL"
              },
              {
                "url": "https://video.twimg.com/amplify_video/2113776813121941504/vid/avc1/480x270/CK1pQpicyNC7ryVp.mp4?tag=16",
                "bitrate": 288000,
                "contentType": "video/mp4"
              }
            ]
          }
        ],
        "metrics": {
          "likes": 5396,
          "comments": 236,
          "views": 900353,
          "reposts": 680,
          "quotes": 59,
          "saves": 259
        },
        "entities": {
          "urls": [
            {
              "url": "https://go.nasa.gov/4jzartX",
              "displayUrl": "go.nasa.gov/4jzartX"
            },
            {
              "url": "https://go.nasa.gov/4zV3TLc",
              "displayUrl": "go.nasa.gov/4zV3TLc"
            }
          ]
        },
        "ext": {
          "conversationId": "2113776971603689874"
        },
        "pinned": true
      }
    ],
    "cursor": "LssW7FrvIb2W_z-EPjiVogYoj3-70ruy8A1hYTEVJNyV1xfWjamuub5cCUPOolr5oPAzKDidQINisvCy-drXkJvvPVGst8_JWWGhxGuKr_D5Ykq9D8H5vhr…",
    "ext": {
      "order": "latest"
    }
  }
}
```

## Errors

| Status | Code | Meaning |
|---|---|---|
| 400 | `INVALID_CURSOR` | The `cursor` is not one this operation returned. Start again without it. |
| 400 | `INVALID_PARAMS` | A parameter is missing, unknown or out of range. The message names it. |
| 401 | `UNAUTHORIZED` | The `x-api-key` header is missing, or the key is revoked or unknown. |
| 402 | `INSUFFICIENT_BALANCE` | The balance does not cover this call. Top up in the dashboard. |
| 404 | `NOT_FOUND` | The account, post or group does not exist, or is private, deleted or age-restricted. |
| 429 | `MARKETPLACE_SATURATED` | Too many concurrent calls. Retry after the `Retry-After` seconds. |
| 502 | `UPSTREAM_ERROR` | The platform answered with something unusable. Retry with backoff. |

Every code is listed in [Errors](/docs/errors). Failed calls are not billed.

## Pricing

**Price** $0.001 per call, plus $0.001 for each extra call it makes — at most 1 more, so $0.002 in total. [List price](https://apinoa.com/en/pricing); the rate steps down above 1,000 calls a day.