# Twitter Content API

v0.9.1

## What is TwitterShots Content API?

**TwitterShots Content API** is a REST API for fetching public X (Twitter) post content as clean, structured Markdown.

Built for developers and AI systems that need reliable, machine-readable tweet text for LLM prompts without scraping HTML.

Use **single-tweet** or **bulk** endpoints to match your throughput. It works well alongside AI coding assistants and agent stacks—for example OpenClaw or Claude Code.

- **Single Tweet:** GET /api/v1/content/:tweetId
- **Bulk Tweets:** POST /api/v1/content/tweets

## Quickstart

Extract tweet content as Markdown via REST API in seconds. This API lets you convert any tweet into structured Markdown format, perfect for content analysis, archiving, AI training data, or integration with documentation systems.

cURLJavaScriptPythonGo

Copy

curl --location 'https://api.twittershots.com/api/v1/content/2036785379303678055' \

--header 'Accept: text/markdown' \

--header 'X-API-KEY: YOUR_X_API_KEY'

## API Reference

Use Content API in 3 simple steps:

1. Get your API key from [Account Settings](/settings/keys)
2. Set X-API-KEY in the request header
3. Send a GET request to the API endpoint

If you're using AI, simply click the **Copy as Markdown** button in the top right.

Docs pages can be copied as markdown, making it easy to feed into an LLM and let AI handle everything.

 If you have other needs, feel free to contact [support@twittershots.com](mailto:support@twittershots.com).

## Base URL

HTTPS-only REST API for secure content extraction.

All requests contain the following base URL:

https://api.twittershots.com

## Authentication

To authenticate you need to add an X-API-KEY header with your API key.

X-API-KEY: YOUR\_API\_KEY

Replace YOUR\_API\_KEY with your actual API key from [Account Settings](/settings/keys).

Remember your API key is a secret. Do not share it with others or expose it in any client-side code.

## Get Single Tweet Content

Endpoint

GEThttps://api.twittershots.com/api/v1/content/:tweetId

Headers

- **Accept**: text/markdown

Path Parameters

- **tweetId**: string (required) \- The tweet ID (numeric string)

## Query Parameters

- includeStats (optional): Include tweet statistics in the markdown

  - true (default): Include reply, retweet, like, and view counts
  - false: Exclude statistics
- includeMedia (optional): Include media URLs in the markdown

  - true (default): Include image and video URLs
  - false: Exclude media URLs
- includeQuoted (optional): Include quoted tweet content

  - true (default): Include quoted tweet content if present
  - false: Exclude quoted tweet content

## Get Bulk Tweet Content

Endpoint

POSThttps://api.twittershots.com/api/v1/content/tweets

Headers

- **Content-Type**: application/json
- **Accept**: application/json

Request Body

- **tweetIds**: string\[\] (required) \- Array of tweet IDs (max 100)

{
  "tweetIds": ["2036785379303678055", "1617979122625712128"]
}

## Response

The Content API returns tweet data formatted as Markdown.

Single Tweet Response:

Returns the markdown text directly in the response body with Content-Type: text/markdown.

**@elonmusk** · 2024-01-15 14:32

This is the tweet content... 🚀

[📷 Image 1](https://pbs.twimg.com/...)

💬 1.2K replies · 🔄 3.4K retweets · ❤️ 12.5K likes · 👁️ 1.2M views

Bulk Response:

Returns a JSON object with an array of markdown results:

{
  "results": [
    {
      "tweetId": "2036785379303678055",
      "markdown": "**@elonmusk** · 2024-01-15...",
      "success": true
    },
    {
      "tweetId": "1617979122625712128",
      "markdown": "**@jack** · 2023-12-01...",
      "success": true
    }
  ],
  "total": 2,
  "successful": 2,
  "failed": 0
}

Response Headers

Each API response includes quota information in the response headers:

- X-Quota-Remaining: Remaining requests in current period
- X-Quota-Limit: Total quota for current period

Example:  
X-Quota-Remaining: 295  
X-Quota-Limit: 300

## Usage

- Free: 50 one-time API credits
- Pro: 300 API credits per month
- Pro+: 1,000 requests per month
- Business: 6,000 requests per month

Monitor Your Usage: Check the X-Quota-Remaining and X-Quota-Limit headers in each API response.

Email Notifications: You'll receive email alerts when your usage reaches 50%, 70%, 90%, and 100% of your quota.

## Response codes

TwitterShots uses standard HTTP codes to indicate the success or failure of your requests.

In general, 2xx HTTP codes correspond to success, 4xx codes are for user-related failures, and 5xx codes are for infrastructure issues.

Reach out to [support@twittershots.com](mailto:support@twittershots.com) for further assistance.

### Status

| Status | Description                                   |
| ------ | --------------------------------------------- |
| 200    | Successful request.                           |
| 400    | Check that the parameters were correct.       |
| 401    | The API key used was missing.                 |
| 403    | The API key used was invalid.                 |
| 404    | The resource was not found.                   |
| 429    | The rate limit was exceeded.                  |
| 5xx    | Indicates an error with TwitterShots servers. |