# X Search Mentions API (https://www.socialcrawl.dev/platforms/twitter/search-mentions)

> Returns X posts that mention an account or reply to it, for tracking a brand or a person. The search is `(@handle OR to:handle)` on /v1/twitter/search/tweets, without the account's own posts unless `include_self=true`, and every row is checked in code: `match_kind` is `mention` (the @handle is in the text), `reply` (the post replies to the account, including replies whose text X shows without the @), `retweet`, or `link` (the post links the account's profile or one of its posts). Rows that pass none of these are left out. Each row in `data.items` is exactly the row the named search endpoint returns, with its `post` and `computed` blocks, plus `match_kind`. `sort` is latest (default) or top; `since` and `until` are sent to X as date operators. Send `data.next_cursor` back as `cursor` for the next page; it is null when every search has run out. `data.legs` reports each search: its endpoint, status, rows returned and kept, credits and `request_id`. `data.excluded` counts the rows left out (`unmatched`, `self`, `duplicate`, `outside_window`). Each page is one /v1/twitter/search/tweets page, 1 credit.

TL;DR: `GET /v1/twitter/search/mentions` costs Metered, 0-1 credits: each call reads one page of /v1/twitter/search/tweets (1 credit), each billed at that endpoint's own price exactly as a direct call is. A page that found nothing or failed costs nothing, and a page served from cache is free. A page is billed when it returned rows, even if none of them carried the mention; data.legs shows each page's charge and data.excluded what was left out. and returns SocialCrawl's unified JSON schema. Single x-api-key auth, 100 free credits on signup.

## Parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `handle` | yes | The account's username, with or without the @, or its profile URL. |
| `cursor` | no | data.next_cursor from the previous response, sent back verbatim for the next page. |
| `since` | no | Only posts published on or after this date, YYYY-MM-DD (UTC). |
| `until` | no | Only posts published on or before this date, YYYY-MM-DD (UTC); that whole day is included. |
| `sort` | no | latest (default) for the newest posts first, top for the most popular. (latest \| top) |
| `include_self` | no | When true, also keep posts by the account itself. Default false. |

## Code example

```bash
curl -G "https://www.socialcrawl.dev/v1/twitter/search/mentions" \
  --data-urlencode "handle=nike" \
  -H "x-api-key: sc_YOUR_API_KEY"
```

See the full X API: https://www.socialcrawl.dev/platforms/twitter

## Pricing

- Standard endpoints: 1 credit per call
- Advanced endpoints: 5 credits per call
- Premium endpoints: 10 credits per call
- 100 free credits on signup, no credit card required. Cached responses cost 0 credits. Credit packs never expire.
- Full pricing: https://www.socialcrawl.dev/pricing