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

# Insights

> Obter insights diários em tempo real de anúncios do Instagram por campanha ou anúncio

export const PlansAvailable = ({plans = [], maxPackRequired}) => {
  let displayPlans = plans;
  if (plans && plans.length === 1) {
    const lowerCasePlan = plans[0].toLowerCase();
    if (lowerCasePlan === "business") {
      displayPlans = ["Launch", "Business", "Enterprise"];
    } else if (lowerCasePlan === "premium") {
      displayPlans = ["Premium", "Launch", "Business", "Enterprise"];
    }
  }
  return <Note>
Available on {displayPlans.length === 1 ? "the " : ""}
{displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "}
{displayPlans.length > 1 ? "plans" : "plan"}.

{maxPackRequired && <span onClick={() => window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer">
 <span className="px-1.5 py-0.5 rounded text-sm" style={{
    backgroundColor: '#C264B6',
    color: 'white',
    fontSize: '12px'
  }}>
   Max Pack required
 </span>
</span>}
</Note>;
};

export const HeaderAPI = ({noProfileKey, profileKeyRequired}) => <>
    <ParamField header="Authorization" type="string" required>
      <a href="/docs/apis/overview#authorization">API Key</a> of the Primary Profile.
      <br />
      <br />
      Format: <code>Authorization: Bearer API_KEY</code>
    </ParamField>
    {!noProfileKey && (profileKeyRequired ? <ParamField header="Profile-Key" type="string" required>
          <a href="/docs/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField> : <ParamField header="Profile-Key" type="string">
          <a href="/docs/apis/overview#profile-key-format">Profile Key</a> of a User Profile.
          <br />
          <br />
          Format: <code>Profile-Key: PROFILE_KEY</code>
        </ParamField>)}
  </>;

<PlansAvailable plans={["premium"]} maxPackRequired={false} />

Obtenha o desempenho em tempo real dos seus anúncios do Instagram, com uma linha por dia, para suas campanhas ou anúncios.
Escolha as métricas desejadas, divida-as por idade, gênero, país ou posicionamento e percorra longos períodos com paginação.

<ul className="custom-bullets">
  <li>Os números são lidos da Meta no momento da chamada, e não de uma cópia noturna.</li>

  <li>
    Use o [Histórico](/docs/apis/ads/instagram/get-ad-history) para o gasto que cobramos. Use os Insights para relatórios
    e análises.
  </li>

  <li>Todos os valores monetários estão na moeda da conta de anúncios, retornada em `currency` em cada linha.</li>

  <li>
    As campanhas devem ter sido criadas pela Ayrshare para este perfil. Um anúncio criado pela
    Ayrshare para outro perfil é recusado. Outros IDs de anúncio são lidos com a conta da Meta vinculada
    a este perfil, então a Meta retorna apenas os anúncios que essa conta pode ver.
  </li>

  <li>
    Uma solicitação abrange uma única conta de anúncios. IDs de várias contas de anúncios retornam o código `101`, assim como
    vários IDs de anúncio dos quais a Ayrshare não tem registro. Solicite-os um de cada vez.
  </li>
</ul>

## Parâmetros de cabeçalho

<HeaderAPI />

## Parâmetros de consulta

<ParamField query="level" type="string" required>
  Sobre o que cada linha informa: `campaign` ou `ad`.

  `adSet` ainda não é suportado e retorna o código `101`.
</ParamField>

<ParamField query="ids" type="string">
  IDs de campanha ou de anúncio separados por vírgula, até 50. Obrigatório para `level=campaign`.

  Com `level=ad`, você pode omitir `ids` e enviar `accountId` no lugar. Isso gera o relatório dos anúncios
  que você criou pela Ayrshare para este perfil nessa conta de anúncios, e não de todos os anúncios dela. Funciona
  para até 50 desses anúncios. Para mais, envie os IDs deles ou gere o relatório por campanha. Se nenhum for encontrado, o
  relatório fica vazio.
</ParamField>

<ParamField query="accountId" type="string">
  O ID da conta de anúncios, com ou sem o prefixo `act_` (`1234567890` ou `act_1234567890`).

  Obrigatório com `level=ad` quando `ids` for omitido.
</ParamField>

<ParamField query="metrics" type="string">
  Métricas a serem retornadas, separadas por vírgula. Omita para obter todas. Veja [Métricas](#metrics).
</ParamField>

<ParamField query="breakdowns" type="string">
  Detalhamentos separados por vírgula: `age`, `gender`, `country`, `placement`. Cada dia passa a ter uma linha por
  valor, ou por combinação no caso de `age,gender`. Envie um detalhamento por vez, ou `age,gender`; a Meta
  recusa outras combinações (como `age,country`), então elas retornam o código `101`.
</ParamField>

<ParamField query="startDate" type="string" default="30 dias atrás">
  Primeiro dia, no formato `YYYY-MM-DD`. Pode ser de até 37 meses atrás.
</ParamField>

<ParamField query="endDate" type="string" default="hoje">
  Último dia, no formato `YYYY-MM-DD`.
</ParamField>

<ParamField query="cursor" type="string">
  O `nextCursor` da resposta anterior, para obter a próxima página.
</ParamField>

<h2 id="metrics">
  Métricas
</h2>

| Métrica | Tipo | Significado |
| - | - | - |
| `spend` | number | Valor gasto |
| `impressions` | number | Vezes que o anúncio foi exibido |
| `reach` | number | Pessoas que viram o anúncio pelo menos uma vez |
| `clicks` | number | Cliques |
| `cpm` | number ou `null` | Custo por 1.000 impressões |
| `cpc` | number ou `null` | Custo por clique. `null` em um dia sem cliques |
| `ctr` | number ou `null` | Taxa de cliques, em porcentagem |
| `actions` | array | Cada tipo de ação contabilizado pela Meta, com sua contagem |
| `conversionValue` | number | Valor total das compras |

O Instagram informa todas as métricas desta tabela. Uma exceção: a Meta não informa `reach` para um relatório com
`breakdowns` que comece há mais de 13 meses, então `reach` é omitido dessas linhas. Em redes que não informam uma métrica, ela é omitida
das linhas em vez de retornada como `0`, e solicitá-la retorna o código `101`.

<Note>
  A Meta contabiliza algumas ações em mais de um tipo, então não some os valores de `actions`. Por
  exemplo, `omni_purchase` já inclui `purchase`. `conversionValue` contabiliza cada compra uma única vez.
</Note>

## Paginação

Cada resposta retorna até 500 linhas. Se houver mais, `nextCursor` é definido. Envie a mesma solicitação
novamente com `cursor` definido com esse valor para obter a próxima página. Na última página, `nextCursor` é `null`.

## Erros

| Código | Quando |
| - | - |
| `101` | Um parâmetro está ausente ou incorreto, um detalhamento ou métrica não é suportado, `level=adSet` é enviado, `startDate` é de mais de 37 meses atrás, mais de 50 IDs são enviados, os IDs estão em mais de uma conta de anúncios ou a Meta recusa a combinação de detalhamentos |
| `400` | Uma campanha ou anúncio não é seu, ou `accountId` não é a conta de anúncios que a Ayrshare tem registrada para os IDs enviados. Para um anúncio sem registro na Ayrshare, `accountId` não é verificado e o anúncio é lido por si só |
| `370` | A Meta não conseguiu retornar os insights. Tente novamente |

<RequestExample>
  ```bash cURL theme={"system"}
  curl \
  -H "Authorization: Bearer API_KEY" \
  -X GET "https://api.ayrshare.com/api/ads/instagram/insights?level=campaign&ids=120200000000000001&startDate=2026-09-01&endDate=2026-09-02"
  ```

  ```javascript JavaScript theme={"system"}
  const API_KEY = "API_KEY";
  const params = new URLSearchParams({
    level: "campaign",
    ids: "120200000000000001",
    startDate: "2026-09-01",
    endDate: "2026-09-02",
  });

  fetch(`https://api.ayrshare.com/api/ads/instagram/insights?${params}`, {
    method: "GET",
    headers: { Authorization: `Bearer ${API_KEY}` },
  })
    .then((res) => res.json())
    .then((json) => console.log(json))
    .catch(console.error);
  ```

  ```python Python theme={"system"}
  import requests

  headers = {'Authorization': 'Bearer API_KEY'}
  params = {
      'level': 'campaign',
      'ids': '120200000000000001',
      'startDate': '2026-09-01',
      'endDate': '2026-09-02',
  }

  r = requests.get('https://api.ayrshare.com/api/ads/instagram/insights', headers=headers, params=params)

  print(r.json())
  ```
</RequestExample>

<ResponseExample>
  ```json 200: Success theme={"system"}
  {
    "status": "success",
    "platform": "instagram",
    "level": "campaign",
    "startDate": "2026-09-01",
    "endDate": "2026-09-02",
    "insights": [
      {
        "date": "2026-09-01",
        "level": "campaign",
        "id": "120200000000000001",
        "currency": "USD",
        "spend": 12.34,
        "impressions": 4000,
        "reach": 3100,
        "clicks": 80,
        "cpm": 3.085,
        "cpc": 0.15425,
        "ctr": 2,
        "actions": [
          { "type": "link_click", "value": 75 },
          { "type": "omni_purchase", "value": 3 }
        ],
        "conversionValue": 89.97
      }
    ],
    "count": 1,
    "nextCursor": null
  }
  ```

  ```json 200: Breakdowns theme={"system"}
  {
    "status": "success",
    "platform": "instagram",
    "level": "ad",
    "startDate": "2026-09-01",
    "endDate": "2026-09-01",
    "insights": [
      {
        "date": "2026-09-01",
        "level": "ad",
        "id": "120210000000000001",
        "age": "25-34",
        "gender": "female",
        "currency": "EUR",
        "spend": 1.5,
        "impressions": 300
      },
      {
        "date": "2026-09-01",
        "level": "ad",
        "id": "120210000000000001",
        "age": "25-34",
        "gender": "male",
        "currency": "EUR",
        "spend": 1,
        "impressions": 200
      }
    ],
    "count": 2,
    "nextCursor": null
  }
  ```

  ```json 400: Not Yours theme={"system"}
  {
    "action": "ads",
    "status": "error",
    "code": 400,
    "message": "The ad is not found or not authorized."
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.