# Truth Social (/docs/truthsocial)

Truth Social profiles, user feeds, and post detail behind the unified schema

Truth Social profiles, an account's recent truths, and full detail on one post. Every endpoint is a `GET` and costs 1 credit, and posts come back as the same canonical `Post` object you get from X or Threads.

Base URL: `/v1/truthsocial/...`

  The platform exposes no keyword search of any kind, so there is no
  `/v1/truthsocial/search` and no way to ask "who mentioned X". Monitoring means
  naming the accounts you care about and walking their feeds.

## Quickstart

### 1. Fetch a profile

```bash
curl "https://www.socialcrawl.dev/v1/truthsocial/profile?handle=realDonaldTrump" \
  -H "x-api-key: YOUR_API_KEY"
```

### 2. Fetch their content

```bash
curl "https://www.socialcrawl.dev/v1/truthsocial/user/posts?handle=realDonaldTrump" \
  -H "x-api-key: YOUR_API_KEY"
```

### 3. Read computed fields

When an endpoint supports a computed field and the required source inputs are present, the unified response includes that optional field. Depending on the endpoint, optional fields can include `engagement_rate`, `language`, `content_category`, and `estimated_reach`. See [Computed fields](/docs/computed-fields.md) for formulas, clamping rules, and null semantics.

## Accounts and posts

| Endpoint                         | Credits | What it returns                                                                         | Key parameters                       |
| -------------------------------- | ------- | --------------------------------------------------------------------------------------- | ------------------------------------ |
| `GET /v1/truthsocial/profile`    | 1       | Display name, bio, follower and following counts, truth count, profile image, `user_id` | `handle`                             |
| `GET /v1/truthsocial/user/posts` | 1       | Recent truths: text, like, retruth and reply counts, media, creation time               | `handle` or `user_id`, `next_max_id` |
| `GET /v1/truthsocial/post`       | 1       | One truth in full                                                                       | `url`                                |

Run `profile` first. It is also where you get the numeric `user_id`. Page deeper through a feed by passing `next_max_id` from the previous response.

```bash
curl "https://www.socialcrawl.dev/v1/truthsocial/user/posts?handle=realDonaldTrump&next_max_id=ID_FROM_PREVIOUS_PAGE" \
  -H "x-api-key: YOUR_API_KEY"
```

## Monitoring without a search endpoint

Two composites make naming accounts cheaper than it sounds.

| Endpoint                          | Credits | What it returns                                                                                                                   |
| --------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `GET /v1/prism/truthsocial-pulse` | 20      | One handle's whole loop: profile, recent posts, a detail drill on the top ones, the news echo, and an activity and sentiment read |
| `GET /v1/prism/voice`             | 5       | One person's posts across X, Threads, Bluesky, and Truth Social merged into a single time-ordered feed                            |

`prism/voice` is usually the real question when someone posts on more than one network.

## All endpoints

## Platform notes

**There is no search on this platform.** No keyword search exists upstream, so nothing here can offer one.

**Identifiers split three ways.** `profile` takes a `handle`, `user/posts` takes `handle` **or** `user_id`, and `post` takes a `url`.

**`user/posts` is the only paginated endpoint,** and it pages with `next_max_id` rather than the universal cursor.

**`trim=true` costs the same.** It works on `user/posts` and returns a lighter payload at the same price.

## Next steps

- [Pagination](/docs/pagination.md): Cursor and page walks, and what has_more actually means.
- [Credits](/docs/credits.md): What each tier costs and when a call is refunded.
- [API reference](/docs/api-reference.md): Every parameter and response field, endpoint by endpoint.
- [Bluesky](/docs/bluesky.md): The other network with no search of its own.
- [Threads](/docs/threads.md): Meta