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

# Referência da API de Audiences

> Referência de endpoints para a X Ads Audiences API, incluindo keyword insights, gerenciamento de custom audiences e detalhes de requisição e resposta para upload de listas de usuários.

## Referência da API

### Keyword Insights

<Button href="https://app.getpostman.com/run-collection/1d12b9fc623b8e149f87">
  Executar no Postman
</Button>

#### GET insights/keywords/search

Dado um grupo de keywords, obtém o volume de Tweets associado, bem como um conjunto de 30 keywords relacionadas. O volume de Tweets corresponde apenas às keywords de entrada, não às keywords relacionadas.

Um intervalo máximo de tempo (`end_time` - `start_time`) de 7 dias é permitido.

Observe que os resultados são delimitados por uma única geo (país).

**URL do recurso**

`https://ads-api.x.com/12/insights/keywords/search`

<ParamField query="granularity" type="enum" required>
  Especifica a granularidade dos dados retornados para o intervalo de tempo indicado por `start_time` e `end_time`. Por exemplo, quando definido como `HOUR`, você recebe um datapoint para cada hora entre `start_time` e `end_time`.<br /><br />
  Valores possíveis: `DAY`, `HOUR`
</ParamField>

<ParamField query="keywords" type="string" required>
  Uma string separada por vírgulas de keywords para restringir a busca. Todas as keywords são combinadas por OR.<br /><br />
  **Nota**: Um máximo de 10 keywords (`keywords` e `negative_keywords` combinadas) pode ser usado.
</ParamField>

<ParamField query="start_time" type="string" required>
  Restringe os dados obtidos aos coletados na janela entre `start_time` e `end_time`. Expresso em [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).
</ParamField>

<ParamField query="end_time" type="string" optional>
  Restringe os dados obtidos aos coletados na janela entre `start_time` e `end_time`. Expresso em [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601).<br /><br />
  **Nota**: Assume o horário atual por padrão.
</ParamField>

<ParamField query="location" type="string" optional>
  Um valor de segmentação que você obtém do endpoint [GET targeting\_criteria/locations](/x-ads-api/campaign-management/reference#get-targeting-criteria-locations) para restringir os resultados em termos de onde o usuário da conta está localizado. Observe que atualmente apenas localizações a nível de país são suportadas.
</ParamField>

<ParamField query="negative_keywords" type="string" optional>
  Uma string separada por vírgulas de keywords a serem excluídas. Todas as negative keywords são combinadas por OR.<br /><br />
  **Nota**: Um máximo de 10 keywords (`keywords` e `negative_keywords` combinadas) pode ser usado.
</ParamField>

**Exemplo de requisição**

```json theme={null}
GET https://ads-api.x.com/12/insights/keywords/search?end_time=2018-02-02&granularity=DAY&keywords=developers&start_time=2018-02-01
```

**Exemplo de resposta**

```json title="Exemplo de resposta" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
    {
      "request": {
        "params": {
          "start_time": "2018-02-01T00:00:00Z",
          "end_time": "2018-02-02T00:00:00Z",
          "granularity": "DAY",
          "keywords": [
            "developers"
          ]
        }
      },
      "data": {
        "related_keywords": [
          "dev",
          "developer",
          "coders",
          "mysql",
          "devs",
          "#technology",
          "#developers",
          "security",
          "programmers",
          "#tech",
          "javascript",
          "#iot",
          "#bigdata",
          "cloud",
          "devops",
          "php",
          "developer",
          "programmer",
          "engineer",
          "big data",
          "agile",
          "app",
          "programming",
          "ios",
          "maker",
          "startups",
          "developer's",
          "java",
          "#devops",
          "startup"
        ],
        "tweet_volume": [
          15707
        ]
      }
    }
```

Para o conteúdo completo desta referência técnica extensa (Tailored Audience Permissions, Targeted Audiences, Custom Audiences Users, Custom Audience Permissions, Custom Audiences, Do Not Reach Lists), consulte a documentação em inglês em [/x-ads-api/audiences/reference](/x-ads-api/audiences/reference). Todos os parâmetros de endpoint, exemplos de requisição/resposta e detalhes técnicos permanecem os mesmos entre as versões em inglês e português.