List Articles API

List Articles returns the caller's own articles at one lifecycle at a time (Draft or Published, default Draft), cursor-paginated at up to 100 per page for $0.0008 a call. X exposes no combined view across both lifecycles, so read both by calling it twice.

curl -X GET "https://example.com/article/list?lifecycle=draft&count=20"

{  "count": 1,  "next_cursor": null,  "articles": [    {      "id": "QXJ0aWNsZUVudGl0eToyMDg2NjUwMjI4OTUwNjgzNjQ4",      "rest_id": "2086650228950683648",      "title": "Why we rebuilt our onboarding from scratch",      "preview_text": "",      "lifecycle": "Draft",      "content_state": {        "blocks": [],        "entityMap": []      },      "cover_media": null,      "media_entities": [],      "author": {        "id": "44196397",        "username": "elonmusk",        "name": "Elon Musk"      },      "created_at_secs": 1786400000,      "modified_at_secs": 1786400120,      "first_published_at_secs": null,      "visibility_setting": null,      "tweet_id": null,      "public_url": null    }  ]}

{  "error": "bad_request",  "message": "Missing or malformed parameter. Fix the request before retrying."}

{  "error": "unauthorized",  "message": "The API key is missing, malformed, or revoked. Check the Authorization header."}

{  "error": "insufficient_credits",  "message": "Your balance is exhausted. Top up your credits to continue."}

{  "error": "not_found",  "message": "The resource does not exist, for example a deleted tweet or a private account."}

{  "error": "rate_limited",  "message": "Too many requests. Back off and retry with exponential backoff."}

{  "error": "server_error",  "message": "Something failed on our side. Retry with backoff; if it persists, contact support."}

Pricing

When to use

Use it to enumerate your own drafts (to find an id to keep editing) or your own published articles (to find an id to unpublish or delete). It cannot read another account's articles; use Get Article for a published article you do not own.

Notes

• Reads only the CALLER's own articles: either register a session once (POST /customer/session), or pass per-call inline credentials as x-auth-token and x-ct0 request headers, which let a single API key act as many accounts. Returns 409 session_required if neither is supplied, 401 session_dead when the session has expired.
• lifecycle is exact-match, not a filter you can combine: draft or published, one call each.
• An empty articles array is a valid answer (no articles at that lifecycle yet), not an error.

Pagination

This endpoint is cursor-paginated and returns roughly 20 records per call. Pass the next_cursor from each response back as the cursor parameter to read the next page. Stop when the records array comes back empty: follower-graph endpoints return a non-null cursor even on the final page, so the empty array is the only reliable stop signal. See Pagination for the full loop.

Related endpoints

• Create Article: Start a new draft article. No request body required.
• Get Article: Read an article via its announcement tweet, or your own via its entity id.
• Delete Article: Delete an article. A draft is hard-deleted; a published article is unpublished, then its announcement tweet is removed too.

FAQ

How do I see both drafts and published articles?

Call it twice: once with lifecycle=draft, once with lifecycle=published. X has no single view that combines both, so there is no third call that returns everything at once.

How many articles come back per call?

Up to count (default 20, max 100) per page. Pass next_cursor from the response back as cursor to read the next page; the list ends when next_cursor is null.