# Truth Social Tag Timeline API Documentation

Request the timeline for a hashtag. Important caveat: this route answers but has been observed to return an empty array every time. Across four measurement rounds and five popular tags it never returned an item, so treat an empty result as the expected outcome rather than a failure or a working discovery surface. Pagination uses the same extracted max_id cursor and the same upper-bound-only date semantics as the user posts endpoint. Search and discovery are not available on this platform without end-user credentials and are therefore not offered here.

- **Documentation:** [https://scrappa.co/docs/truthsocial-api/truthsocial_tag_timeline](https://scrappa.co/docs/truthsocial-api/truthsocial_tag_timeline)
- **API group:** Truth Social API
- **Endpoint:** `GET https://scrappa.co/api/truthsocial/tag-timeline`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `tag` | string | Yes | Hashtag without the leading #. |
| `limit` | integer | No | Requested page size. The upstream returns 20 regardless. |
| `max_id` | string | No | Cursor from a previous response. Use the returned next cursor. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/truthsocial/tag-timeline?tag=trump"
```

## Example response

```json
{
    "success": true,
    "statuses": [],
    "count": 0,
    "pagination": {
        "next": null,
        "has_more": false
    },
    "caveats": [
        "This hashtag timeline currently returns an empty array upstream. An empty result is the expected outcome, not an error."
    ]
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 404 | Not found | No public account, truth, tag or video matches the given identifier. One upstream lookup was performed and the request was not charged. |
| 422 | Validation error | A required identifier was missing or malformed. No upstream request was performed and nothing was charged. |
| 503 | Upstream unavailable | Truth Social could not be reached after safe retries. The request is not billed. A challenge, a regional block or a rate limit on our side is reported this way, never as a rate limit against you. The specific cause is recorded on your request log, not in this response. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)