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

# Búsqueda de publicaciones

> Endpoint POST para buscar publicaciones de X (Twitter) mediante palabras clave y operadores.

`/search-tweets` consulta el índice público de búsqueda de X (Twitter) mediante palabras clave y operadores. Devuelve las publicaciones coincidentes con los perfiles completos de sus autores y sus métricas de interacción.

Consulta patrones de uso, plantillas de consultas y código funcional en la [guía de búsqueda mediante API](https://api.sorsa.io/blog/twitter-search-api) del blog.

## Endpoint

```text theme={null}
POST https://api.sorsa.io/v3/search-tweets
```

## Autenticación

Envía la clave en el encabezado `ApiKey`. Los nombres de encabezados HTTP no distinguen mayúsculas de minúsculas; el valor de la clave debe coincidir exactamente con el emitido.

```text theme={null}
ApiKey: YOUR_API_KEY
```

Consulta [Autenticación](https://docs.sorsa.io/es/authentication).

## Cuerpo de la solicitud

| Parámetro     | Tipo   | Obligatorio | Descripción                                                                                      |
| :------------ | :----- | :---------- | :----------------------------------------------------------------------------------------------- |
| `query`       | string | Sí          | Palabras clave y operadores. Admite el conjunto completo de operadores nativos de búsqueda de X. |
| `order`       | string | No          | `"popular"` (predeterminado), equivalente a la pestaña Top, o `"latest"` para orden cronológico. |
| `next_cursor` | string | No          | Cursor de la respuesta anterior. Omítelo en la primera solicitud.                                |

### Ejemplo de solicitud

```bash theme={null}
curl -X POST https://api.sorsa.io/v3/search-tweets \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "artificial intelligence lang:en",
    "order": "latest"
  }'
```

## Respuesta

```json theme={null}
{
  "tweets": [
    {
      "id": "2029914600217473314",
      "full_text": "The latest breakthroughs in AI are reshaping automation.",
      "created_at": "2026-03-06T13:38:49Z",
      "lang": "en",
      "conversation_id_str": "2029914600217473314",
      "likes_count": 142,
      "retweet_count": 38,
      "reply_count": 12,
      "quote_count": 5,
      "view_count": 28400,
      "bookmark_count": 19,
      "is_reply": false,
      "is_quote_status": false,
      "entities": [],
      "user": {
        "id": "1422280682240450563",
        "username": "tech_insider",
        "display_name": "Tech Insider",
        "followers_count": 84200,
        "verified": true
      }
    }
  ],
  "next_cursor": "DAABCgABGSmiaxkAAgoAAgjEJ..."
}
```

Cada publicación incluye el perfil completo del autor. No hace falta una consulta adicional para añadir sus datos.

> Consulta todos los campos en [Formato de respuesta](https://docs.sorsa.io/es/response-format).

## Operadores de consulta

`query` admite los operadores nativos de X, incluidos:

* **Palabras clave y frases exactas:** `"climate change"`.
* **Filtros de usuarios:** `from:`, `to:`, `@mention`.
* **Filtros de interacción:** `min_faves:`, `min_retweets:`, `min_replies:`.
* **Filtros de contenido:** `filter:media`, `filter:images`, `filter:videos`, `filter:links`; añade `-` delante para excluir.
* **Idioma y fechas:** `lang:en`, `since:2026-01-01`, `until:2026-03-01`.
* **Lógica booleana:** `OR`, paréntesis para agrupar y `-` para excluir.

> Referencia completa: [Operadores de búsqueda](https://docs.sorsa.io/es/search-operators).

## Paginación

La respuesta incluye `next_cursor`. Para obtener la siguiente página, repite la misma solicitud con ese valor. Si el campo es `null` o no aparece, se han agotado los resultados.

> Consulta los patrones y casos especiales en [Paginación](https://docs.sorsa.io/es/pagination).

## Límite de solicitudes

20 solicitudes por segundo y por clave de API en todos los planes. Si se supera, la respuesta es `429 Too Many Requests`. Consulta [Límites de solicitudes](https://docs.sorsa.io/es/rate-limits).

## Códigos de error

| Código | Significado                                           |
| :----- | :---------------------------------------------------- |
| `200`  | OK                                                    |
| `400`  | Solicitud incorrecta: parámetros no válidos           |
| `401`  | No autorizado: falta la clave de API o no es válida   |
| `403`  | Prohibido: cuota agotada o suscripción caducada       |
| `429`  | Demasiadas solicitudes: límite de frecuencia superado |
| `500`  | Error interno del servidor                            |

> Consulta la lista completa en [Códigos de error](https://docs.sorsa.io/es/error-codes).

## Endpoints relacionados

* [Seguimiento de menciones](https://docs.sorsa.io/es/api-reference/b%C3%BAsqueda/buscar-menciones): seguimiento específico de `@handle` con más filtros en el cuerpo de la solicitud.
* [Publicaciones de un usuario](https://docs.sorsa.io/es/api-reference/publicaciones/publicaciones-del-usuario): cronología de una cuenta.
* [Búsqueda de usuarios](https://docs.sorsa.io/es/api-reference/b%C3%BAsqueda/buscar-usuarios): encuentra cuentas por palabras clave.