# Search Tweets (https://snitchfeed.com/docs/api/twitter/tweets/search)

**Authentication:** All requests require `Authorization: Bearer <api_key>` header. Obtain your API key from the SnitchFeed platform under Integrations → API Keys.

## `POST /data/twitter/tweets/search`

**Full URL:** `https://api.snitchfeed.com/v1/data/twitter/tweets/search`

**Summary:** Search Tweets

Search public posts on X (Twitter) by keyword with cursor pagination. Each successful request costs 2 credits; failed requests are not billed.

Credits

Each **successful** response deducts **2 credits** from your organization. Requests that fail (4xx / 5xx) are not billed.

See the [credits documentation](https://snitchfeed.com/docs/api/credits) for the full rate table.

### Request Body

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

#### Fields

Request body for `POST /data/twitter/tweets/search`.

| Field | Type | Required | Description |
|-------|------|:--------:|-------------|
| `query` | string | ✓ | Search keywords for posts on X. (minLength: 1, maxLength: 200) |
| `cursor` | string |  | Opaque cursor from a previous response `meta.nextCursor`. (maxLength: 1024) |
| `count` | integer |  | Maximum tweets to return (capped at 20). Default: `20`. (min: 1, max: 20) |
| `category` | "Top", "Latest", "People", "Photos", "Videos" |  | Search tab / category on X. |
| `filters` | object |  | Additional structured filters (subset of upstream search). |
| `lang` | string |  | BCP 47 language filter. (maxLength: 32) |
| `since` | string |  | Start of time window (upstream format). (maxLength: 32) |
| `until` | string |  | End of time window (upstream format). (maxLength: 32) |
| `exactSentence` | string |  | Exact phrase match (defaults to main query if omitted upstream). (maxLength: 512) |
| `anyOfTheseWords` | string[] |  | Match if any of these words appear. |
| `noneOfTheseWords` | string[] |  | Exclude posts containing these words. |
| `hashtags` | string[] |  | Hashtag filters without leading `#`. |
| `fromTheseAccounts` | string[] |  | Only posts from these screen names or handles. |
| `toTheseAccounts` | string[] |  | Posts directed at these accounts. |
| `mentionsTheseAccounts` | string[] |  | Posts mentioning these accounts. |
| `removePostsWithLinks` | boolean |  | Exclude posts with URLs. |
| `onlyPostsWithLinks` | boolean |  | Only posts with URLs. |
| `removeReplies` | boolean |  | Exclude replies. |
| `onlyReplies` | boolean |  | Only replies. |
| `removePostsWithMedia` | boolean |  | Exclude posts with media. |
| `onlyPostsWithMedia` | boolean |  | Only posts with media. |
| `removePostsWithVideo` | boolean |  | Exclude posts with video. |
| `onlyPostsWithVideo` | boolean |  | Only posts with video. |
| `removePostsWithPhotos` | boolean |  | Exclude posts with photos. |
| `onlyPostsWithPhotos` | boolean |  | Only posts with photos. |
| `linksInclude` | string |  | Posts must include a link matching this substring. (maxLength: 200) |
| `minimumRepliesCount` | integer |  | Minimum reply count. (min: 0) |
| `minimumRetweetsCount` | integer |  | Minimum repost/retweet count. (min: 0) |
| `minimumLikesCount` | integer |  | Minimum like count. (min: 0) |
| `geocode` | string |  | Location bias string for geographic search. (maxLength: 120) |
| `radius` | number |  | Radius used with geocode (upstream units). |

### Responses

#### `200`: Search results

#### Response fields

Successful `POST /data/twitter/tweets/search` response.

| Field | Type | Required | Description |
|-------|------|:--------:|-------------|
| `requestId` | string | ✓ | Server-generated id for this request (logging / support). |
| `posts` | object[] | ✓ | Matching posts for this page. |
| `meta` | object | ✓ | Pagination metadata for tweet search. |
| `returnedCount` | integer | ✓ | Number of posts returned in this response. (min: 0) |
| `hasMore` | boolean | ✓ | Whether more results exist beyond this page. |
| `nextCursor` | string |  | Pass as `cursor` in the next request to fetch the next page. |

#### `400`: Validation or bad request

#### Response fields

Validation error

| Field | Type | Required | Description |
|-------|------|:--------:|-------------|
| `requestId` | string | ✓ | Server-generated id for this request (logging / support). |
| `error` | object | ✓ |  |
| `code` | "validation_error" | ✓ |  |
| `message` | string | ✓ |  |
| `issues` | object[] | ✓ |  |

**Example:**
```json
{
  "requestId": "01HXYZABCDEF",
  "error": {
    "code": "validation_error",
    "message": "query: String must contain at least 1 character(s)",
    "issues": [
      {
        "path": "query",
        "message": "String must contain at least 1 character(s)"
      }
    ]
  }
}
```

#### `401`: Unauthorized

#### Response fields

Unauthorized

| Field | Type | Required | Description |
|-------|------|:--------:|-------------|
| `requestId` | string | ✓ | Server-generated id for this request (logging / support). |
| `error` | object | ✓ |  |
| `code` | "unauthorized" | ✓ |  |
| `message` | string | ✓ |  |

**Example:**
```json
{
  "requestId": "01HXYZABCDEF",
  "error": {
    "code": "unauthorized",
    "message": "Invalid or revoked API key."
  }
}
```

#### `403`: Forbidden: the credential lacks the `search:read` scope, the organization's plan does not include API access (API keys only), or the authorizing user's role lacks the required permission.

#### Response fields

Forbidden — the API key lacks a required scope, or its owner's role lacks the underlying permission.

| Field | Type | Required | Description |
|-------|------|:--------:|-------------|
| `requestId` | string | ✓ | Server-generated id for this request (logging / support). |
| `error` | object | ✓ |  |
| `code` | "forbidden" | ✓ |  |
| `message` | string | ✓ |  |

**Example:**
```json
{
  "requestId": "01HXYZABCDEF",
  "error": {
    "code": "forbidden",
    "message": "This credential does not have the \"search:read\" scope."
  }
}
```

#### `429`: Rate limited (20 requests per minute per surface) or too many concurrent in-flight requests (max 2 per organization)

#### Response fields

Rate limited or too many concurrent in-flight requests

| Field | Type | Required | Description |
|-------|------|:--------:|-------------|
| `requestId` | string | ✓ | Server-generated id for this request (logging / support). |
| `error` | object | ✓ |  |
| `code` | "rate_limited" | ✓ |  |
| `message` | string | ✓ |  |
| `retryAfter` | integer | ✓ | Seconds until the rate limit resets (same value as the `Retry-After` response header). |

**Example:**
```json
{
  "requestId": "01HXYZABCDEF",
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded for linkedin. Try again later.",
    "retryAfter": 42
  }
}
```

#### `502`: Upstream error

#### Response fields

Upstream error

| Field | Type | Required | Description |
|-------|------|:--------:|-------------|
| `requestId` | string | ✓ | Server-generated id for this request (logging / support). |
| `error` | object | ✓ |  |
| `code` | "upstream_error" | ✓ |  |
| `message` | string | ✓ |  |

**Example:**
```json
{
  "requestId": "01HXYZABCDEF",
  "error": {
    "code": "upstream_error",
    "message": "Upstream request failed."
  }
}
```
