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

> Obtener insights diarios en tiempo real de anuncios de Instagram por campaña, conjunto de anuncios o anuncio

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} />

Obtén el rendimiento en tiempo real de tus anuncios de Instagram, una fila por día, para tus campañas, conjuntos de anuncios o anuncios.
Elige las métricas que quieres, desglósalas por edad, género, país o ubicación, y recorre rangos de fechas largos por páginas.

<ul className="custom-bullets">
  <li>Los números se leen de Meta en el momento de la llamada, no de una copia nocturna.</li>

  <li>
    Usa [Historial](/docs/apis/ads/instagram/get-ad-history) para el gasto que facturamos. Usa Insights para informes
    y análisis.
  </li>

  <li>Todos los valores monetarios están en la moneda de la cuenta publicitaria, que se devuelve en `currency` en cada fila.</li>

  <li>
    Las campañas deben haberse creado a través de Ayrshare para este perfil, y los conjuntos de anuncios deben estar en una de esas campañas. Un anuncio creado a través de
    Ayrshare para otro perfil se rechaza. Los demás IDs de anuncio se leen con la cuenta de Meta vinculada
    a este perfil, por lo que Meta solo devuelve los anuncios que esa cuenta puede ver.
  </li>

  <li>
    Una solicitud abarca una sola cuenta publicitaria. Los IDs de varias cuentas publicitarias devuelven el código `101`, al igual que
    varios IDs de anuncio de los que Ayrshare no tiene registro. Solicítalos de uno en uno.
  </li>
</ul>

## Parámetros del encabezado

<HeaderAPI />

## Parámetros de consulta

<ParamField query="level" type="string" required>
  Sobre qué informa cada fila: `campaign`, `adSet` o `ad`.
</ParamField>

<ParamField query="ids" type="string">
  IDs de campaña, de conjunto de anuncios o de anuncio separados por comas, hasta 50. Obligatorio para `level=campaign` y `level=adSet`.

  Con `level=ad`, puedes omitir `ids` y enviar `accountId` en su lugar. Esto informa sobre los anuncios
  que creaste a través de Ayrshare para este perfil en esa cuenta publicitaria, no sobre todos los anuncios de ella. Funciona
  con hasta 50 de esos anuncios. Si hay más, envía sus IDs o genera el informe por campaña. Si no se encuentra ninguno, el
  informe está vacío.
</ParamField>

<ParamField query="accountId" type="string">
  El ID de la cuenta publicitaria, con o sin el prefijo `act_` (`1234567890` o `act_1234567890`).

  Obligatorio con `level=ad` cuando se omite `ids`.
</ParamField>

<ParamField query="metrics" type="string">
  Métricas que se devolverán, separadas por comas. Omítelo para obtenerlas todas. Consulta [Métricas](#metrics).
</ParamField>

<ParamField query="breakdowns" type="string">
  Desgloses separados por comas: `age`, `gender`, `country`, `placement`. Cada día tendrá entonces una fila por
  valor, o por combinación con `age,gender`. Envía un desglose a la vez, o `age,gender`; Meta
  rechaza otras combinaciones (como `age,country`), por lo que devuelven el código `101`.
</ParamField>

<ParamField query="startDate" type="string" default="hace 30 días">
  Primer día, en formato `YYYY-MM-DD`. Puede ser de hasta hace 37 meses.
</ParamField>

<ParamField query="endDate" type="string" default="hoy">
  Último día, en formato `YYYY-MM-DD`.
</ParamField>

<ParamField query="cursor" type="string">
  El `nextCursor` de la respuesta anterior, para obtener la página siguiente.
</ParamField>

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

| Métrica | Tipo | Significado |
| - | - | - |
| `spend` | number | Importe gastado |
| `impressions` | number | Veces que se mostró el anuncio |
| `reach` | number | Personas que vieron el anuncio al menos una vez |
| `clicks` | number | Clics |
| `cpm` | number o `null` | Costo por cada 1,000 impresiones |
| `cpc` | number o `null` | Costo por clic. `null` en un día sin clics |
| `ctr` | number o `null` | Tasa de clics (CTR), en porcentaje |
| `actions` | array | Cada tipo de acción que Meta contabilizó, con su recuento |
| `conversionValue` | number | Valor total de las compras |

Instagram informa todas las métricas de esta tabla. Una excepción: Meta no informa `reach` para un informe con
`breakdowns` que comienza hace más de 13 meses, por lo que `reach` se omite en esas filas. En las redes que no informan una métrica, esta se omite
de las filas en lugar de devolverse como `0`, y solicitarla devuelve el código `101`.

<Note>
  Meta contabiliza algunas acciones en más de un tipo, así que no sumes los valores de `actions`. Por
  ejemplo, `omni_purchase` ya incluye `purchase`. `conversionValue` cuenta cada compra una sola vez.
</Note>

<h2 id="paging">
  Paginación
</h2>

Cada respuesta devuelve hasta 500 filas. Si hay más, se establece `nextCursor`. Envía la misma solicitud
de nuevo con `cursor` establecido en ese valor para obtener la página siguiente. En la última página, `nextCursor` es `null`.

<h2 id="errors">
  Errores
</h2>

| Código | Cuándo |
| - | - |
| `101` | Falta un parámetro o es incorrecto, un desglose o una métrica no es compatible, `startDate` es de hace más de 37 meses, se envían más de 50 IDs, los IDs pertenecen a más de una cuenta publicitaria, o Meta rechaza la combinación de desgloses |
| `400` | Una campaña, un conjunto de anuncios o un anuncio no es tuyo, o `accountId` no es la cuenta publicitaria que Ayrshare tiene registrada para los IDs que enviaste. Para un conjunto de anuncios, `accountId` también debe ser la cuenta publicitaria que Meta indica para él. Para un anuncio sin registro en Ayrshare, `accountId` no se comprueba y el anuncio se lee por sí solo |
| `370` | Meta no pudo devolver los insights. Inténtalo de nuevo |

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