> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usegoro.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Twitter search

> Search recent tweets on X (Twitter) by keyword, hashtag, or advanced query and get back tweet text, author, and engagement metrics.

Search recent tweets on X (Twitter) by keyword, hashtag, or advanced query and get back tweet text, author, and engagement metrics.

<Note>Use when you need tweets about a topic, sentiment or chatter on X, mentions of a brand or person, or what people are saying right now.</Note>

## Price

**\$0.0012 per result.** That is the rate you pay for each result the call returns, so the total depends on how many it produces.

Billing follows actual usage, so a call that returns fewer results costs less. `discover` and `inspect` also return a ceiling for your specific request, which is a maximum you will never be charged above.

## Input

| Field          | Type            | Required | Notes                                                                                                           |
| -------------- | --------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| `end`          | `string`        |          | Only tweets before this date, YYYY-MM-DD                                                                        |
| `sort`         | `Top`, `Latest` |          | Rank by relevance (Top) or recency (Latest) Defaults to `"Latest"`.                                             |
| `start`        | `string`        |          | Only tweets after this date, YYYY-MM-DD                                                                         |
| `author`       | `string`        |          | Only tweets sent by this handle. PERSONAL DATA: this points the search at one named person.                     |
| `geocode`      | `string`        |          | Only tweets from users inside a radius of a coordinate, as latitude,longitude,radius, e.g. 37.781,-122.398,1mi. |
| `maxItems`     | `integer`       |          | Maximum tweets to return across all search terms Defaults to `20`.                                              |
| `inReplyTo`    | `string`        |          | Only tweets that are replies to this handle.                                                                    |
| `onlyImage`    | `boolean`       |          | Only tweets containing an image.                                                                                |
| `onlyQuote`    | `boolean`       |          | Only quote tweets.                                                                                              |
| `onlyVideo`    | `boolean`       |          | Only tweets containing video.                                                                                   |
| `startUrls`    | `array`         |          | X URLs to scrape directly instead of searching. Tweet, profile, search and list URLs all work.                  |
| `mentioning`   | `string`        |          | Only tweets mentioning this handle.                                                                             |
| `searchTerms`  | `array`         | yes      | Search queries. Supports X advanced search syntax.                                                              |
| `withinRadius` | `string`        |          | Radius around geotaggedNear, e.g. 15km.                                                                         |

<Note>
  Goro forwards your input to the underlying tool unchanged, so any field the
  tool accepts works here even if it is not listed above.
</Note>

## Example

```bash theme={null}
curl -X POST https://api.usegoro.ai/v1/run \
  -H "Authorization: Bearer $GORO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slug":"twitter.search","input":{"searchTerms":["example"],"maxItems":3}}'
```

## Response

One row of the response. Values are illustrative.

```json theme={null}
{
  "id": "1811230000000000000",
  "url": "https://x.com/example-account/status/1811230000000000000",
  "text": "AI agents are eating the software stack",
  "likes": 42,
  "replies": 3,
  "retweets": 7,
  "created_at": "2026-07-01T12:00:00Z",
  "author_name": "Builder",
  "author_handle": "builder"
}
```