> ## 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.

# Otimização do uso da API

Reduza chamadas desnecessárias reutilizando perfis incluídos nas respostas, consultando em lote e armazenando por ID estável.

> As 100 requisições gratuitas, sem cartão nem validade, permitem prototipar e medir o consumo antes de escolher um plano.

## Configuração dos exemplos

Use Python com `requests` (`python -m pip install requests`) no backend. Substitua chave e IDs de exemplo. `search_results` representa uma lista de publicações obtida anteriormente.

```python theme={null}
import requests

API_KEY = "YOUR_API_KEY"
```

## 1. Publicações já incluem os dados do autor

`/search-tweets`, `/user-tweets`, `/list-tweets`, `/comments`, `/quotes` e `/mentions` incluem o **perfil completo** em cada publicação.

```json theme={null}
{
  "tweets": [
    {
      "id": "2029914600217473314",
      "full_text": "Great thread on API design patterns...",
      "likes_count": 142,
      "user": {
        "id": "1422280682240450563",
        "username": "dev_sarah",
        "display_name": "Sarah Chen",
        "description": "Staff engineer @stripe. APIs, distributed systems.",
        "followers_count": 12400,
        "followings_count": 890,
        "tweets_count": 4521,
        "verified": true,
        "location": "San Francisco",
        "created_at": "2021-02-01T09:15:22Z"
      }
    }
  ]
}
```

`user` contém os mesmos dados de uma chamada `/info`: ID, nomes, bio, contadores, verificação, localização, criação, imagens e mais. Para montar uma lista de autores de um tema, extraia os perfis diretamente:

```python theme={null}
# Collect unique users from a tweet search - zero extra API calls
seen_ids = set()
unique_users = []

for tweet in search_results:
    user = tweet["user"]
    if user["id"] not in seen_ids:
        seen_ids.add(user["id"])
        unique_users.append(user)

print(f"Found {len(unique_users)} unique users from {len(search_results)} tweets")
```

Isso pode eliminar centenas ou milhares de chamadas extras em um fluxo.

## 2. Use endpoints em lote

### info-batch em vez de chamadas individuais a info

Consulte até 100 perfis por vez:

```python theme={null}
# A separate /info call for each account would use 10 requests.

# Efficient: 10 accounts = 1 request
resp = requests.get(
    "https://api.sorsa.io/v3/info-batch",
    headers={"ApiKey": API_KEY},
    params={"usernames": ["NASA", "SpaceX", "Tesla", "OpenAI", "stripe",
                           "shopify", "vercel", "github", "notion", "linear"]},
)
resp.raise_for_status()
profiles = resp.json().get("users", [])
```

Dez contas exigem uma chamada em vez de dez; a economia cresce até 100 contas por lote.

### tweet-info-bulk em vez de chamadas individuais a tweet-info

Atualize até 100 IDs de publicações com métricas e dados de autor:

```python theme={null}
# A separate /tweet-info call for each tweet would use up to 100 requests.

# Efficient: 100 tweets = 1 request
resp = requests.post(
    "https://api.sorsa.io/v3/tweet-info-bulk",
    headers={"ApiKey": API_KEY, "Content-Type": "application/json"},
    json={
        "tweet_links": [
            "https://x.com/user/status/111111",
            "https://x.com/user/status/222222",
            # ... up to 100 links
        ]
    },
)
resp.raise_for_status()
tweets = resp.json().get("tweets", [])
```

Cem publicações exigem uma chamada em vez de cem, redução de 99%.

## 3. Use listas para várias contas

Agrupe contas em uma lista do X e consulte `/list-tweets` em vez de cada `/user-tweets` separadamente.

```python theme={null}
# Separate /user-tweets calls would use 30 requests per polling cycle.
LIST_ID = "YOUR_LIST_ID"

# Efficient: 1 request covers all 30 accounts
resp = requests.get(
    f"https://api.sorsa.io/v3/list-tweets?list_id={LIST_ID}",
    headers={"ApiKey": API_KEY},
    timeout=30,
)
resp.raise_for_status()
```

**Estimativa para primeiras páginas:** uma lista a cada 10 segundos usa 259.200 chamadas em 30 dias; 30 timelines separadas usam 7.776.000. Páginas extras e novas tentativas aumentam os totais, e listas movimentadas exigem paginação por ciclo.

Veja [monitoramento em tempo real](https://docs.sorsa.io/pt-BR/real-time-monitoring) e [listas e comunidades](https://docs.sorsa.io/pt-BR/lists-and-communities).

## 4. Use info para resolver identificadores e obter perfis

`/info` aceita nome, ID ou URL e retorna o perfil com o ID permanente. Se você precisa do perfil, não faça uma conversão `/username-to-id` ou `/link-to-id` antes:

```python theme={null}
# Resolving an ID and then fetching its profile would use two requests.

# Efficient: 1 request per account
response = requests.get(
    "https://api.sorsa.io/v3/info",
    headers={"ApiKey": API_KEY},
    params={"username": "stripe"},       # accepts username, user_id, or user_link
    timeout=30,
)
response.raise_for_status()
profile = response.json()
# profile already contains the user ID, plus everything else
```

Use conversão separada quando precisar apenas do ID ou nome. Se uma etapa anterior já retornou o perfil, reutilize `id`. Veja [conversão de IDs](https://docs.sorsa.io/pt-BR/ID-Conversion).

## 5. Deduplique no banco

O mesmo usuário pode aparecer em buscas, seguidores, menções e timelines. Use o ID permanente como chave e atualize registros existentes.

```python theme={null}
import sqlite3

db = sqlite3.connect("audience.db")
db.execute("""
    CREATE TABLE IF NOT EXISTS users (
        user_id TEXT PRIMARY KEY, username TEXT, display_name TEXT,
        description TEXT, followers_count INTEGER, tweets_count INTEGER,
        verified INTEGER, updated_at TEXT
    )
""")

def upsert_user(db, user):
    """Insert or update a user record keyed by permanent User ID."""
    db.execute("""
        INSERT INTO users (user_id, username, display_name, description,
                          followers_count, tweets_count, verified, updated_at)
        VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now'))
        ON CONFLICT(user_id) DO UPDATE SET
            username = excluded.username,
            display_name = excluded.display_name,
            description = excluded.description,
            followers_count = excluded.followers_count,
            tweets_count = excluded.tweets_count,
            verified = excluded.verified,
            updated_at = datetime('now')
    """, (
        user["id"], user["username"], user.get("display_name", ""),
        user.get("description", ""), user.get("followers_count", 0),
        user.get("tweets_count", 0), user.get("verified", False),
    ))
    db.commit()


# Every time you encounter a user in any API response, upsert:
for tweet in search_results:
    upsert_user(db, tweet["user"])
    # The user's profile data stays fresh without separate /info calls
```

O perfil é atualizado quando reaparece em uma resposta. Contas que não reaparecem ficam sem atualização; agende consultas em lote se a aplicação exigir um intervalo definido de atualização.

## 6. Reutilize dados entre etapas

**Localização da audiência:** após obter seguidores, você já tem os perfis. Consulte apenas `/about` para o país; não chame `/info` novamente. Veja [localização da audiência](https://docs.sorsa.io/pt-BR/Audience-Geography).

**Campanhas:** quando `/check-comment` retorna `commented: true`, o comentário completo já está na resposta. Analise-o sem buscar novamente com `/search-tweets` ou `/comments`.

**Autores de buscas:** para selecionar usuários com mais de 10 mil seguidores entre 500 autores únicos, filtre os objetos `user` já obtidos, sem 500 consultas extras.

## Escolha o endpoint adequado

| Você tem            | Precisa de           | Use                                      | Evite                                |
| :------------------ | :------------------- | :--------------------------------------- | :----------------------------------- |
| Lista de nomes      | Perfis completos     | `GET /info-batch`                        | `/info` em loop                      |
| URLs de publicações | Conteúdo e autores   | `POST /tweet-info-bulk`, até 100/chamada | `/tweet-info` em loop                |
| 30 contas           | Publicações recentes | `GET /list-tweets`                       | 30 chamadas `/user-tweets`           |
| Um nome de usuário  | ID e perfil completo | `GET /info`                              | `/username-to-id` seguido de `/info` |
| Resultados de busca | Perfis dos autores   | Extraia `tweet["user"]`                  | `/info` por autor                    |
| Lista de seguidores | Dados dos perfis     | Já estão em `/followers`                 | `/info` por seguidor                 |

## Estime o orçamento

| Tarefa                                  | Abordagem                  | Requisições |
| :-------------------------------------- | :------------------------- | :---------- |
| 50 perfis                               | `/info-batch`              | \~1         |
| 10.000 seguidores                       | `/followers`, 200/página   | 50          |
| País dos 10.000 seguidores              | `/about` para cada um      | 10.000      |
| Métricas atuais de 100 publicações      | `/tweet-info-bulk`         | 1           |
| 50 contas a cada 10 segundos por um dia | `/list-tweets`             | 8.640       |
| 5 tarefas para 1.000 participantes      | 5 verificações por usuário | 5.000       |

Um fluxo combinado pode consumir 50 + 10.000 + 1 + 8.640 + 5.000 = cerca de 23.700 chamadas. A 20 req/s, o limite inferior teórico é de aproximadamente 20 minutos, mas o monitoramento ainda ocupa um dia inteiro. Paginação sequencial, latência e tentativas também aumentam o tempo. Veja [preços](https://api.sorsa.io/pricing).

## Próximos passos

* [Limites](https://docs.sorsa.io/pt-BR/rate-limits): erros 429 e frequência.
* [Paginação](https://docs.sorsa.io/pt-BR/pagination): extração em escala.
* [Preços](https://api.sorsa.io/pricing): custo e orçamento.
* [Referência](https://docs.sorsa.io/pt-BR/api-reference-guide): especificações.