curl \
-H "Authorization: Bearer API_KEY" \
-X GET "https://api.ayrshare.com/api/ads/facebook/insights?level=campaign&ids=120200000000000001&startDate=2026-09-01&endDate=2026-09-02"
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/facebook/insights?${params}`, {
method: "GET",
headers: { Authorization: `Bearer ${API_KEY}` },
})
.then((res) => res.json())
.then((json) => console.log(json))
.catch(console.error);
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/facebook/insights', headers=headers, params=params)
print(r.json())
{
"status": "success",
"platform": "facebook",
"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
}
{
"status": "success",
"platform": "facebook",
"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
}
{
"action": "ads",
"status": "error",
"code": 400,
"message": "The ad is not found or not authorized."
}
Facebook Ads
Insights
Obtener insights diarios en tiempo real de anuncios de Facebook por campaña, conjunto de anuncios o anuncio
GET
/
ads
/
facebook
/
insights
curl \
-H "Authorization: Bearer API_KEY" \
-X GET "https://api.ayrshare.com/api/ads/facebook/insights?level=campaign&ids=120200000000000001&startDate=2026-09-01&endDate=2026-09-02"
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/facebook/insights?${params}`, {
method: "GET",
headers: { Authorization: `Bearer ${API_KEY}` },
})
.then((res) => res.json())
.then((json) => console.log(json))
.catch(console.error);
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/facebook/insights', headers=headers, params=params)
print(r.json())
{
"status": "success",
"platform": "facebook",
"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
}
{
"status": "success",
"platform": "facebook",
"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
}
{
"action": "ads",
"status": "error",
"code": 400,
"message": "The ad is not found or not authorized."
}
Obtén el rendimiento en tiempo real de tus anuncios de Facebook, 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.
Facebook informa todas las métricas de esta tabla. Una excepción: Meta no informa
- Los números se leen de Meta en el momento de la llamada, no de una copia nocturna.
- Usa Historial para el gasto que facturamos. Usa Insights para informes y análisis.
- Todos los valores monetarios están en la moneda de la cuenta publicitaria, que se devuelve en
currencyen cada fila. - 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.
- 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.
Parámetros del encabezado
Parámetros de consulta
string
requerido
Sobre qué informa cada fila:
campaign, adSet o ad.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.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.string
Métricas que se devolverán, separadas por comas. Omítelo para obtenerlas todas. Consulta Métricas.
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.string
predeterminado:"hace 30 días"
Primer día, en formato
YYYY-MM-DD. Puede ser de hasta hace 37 meses.string
predeterminado:"hoy"
Último día, en formato
YYYY-MM-DD.string
El
nextCursor de la respuesta anterior, para obtener la página siguiente.Métricas
| 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 |
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.
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.Paginación
Cada respuesta devuelve hasta 500 filas. Si hay más, se establecenextCursor. 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.
Errores
| 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 |
curl \
-H "Authorization: Bearer API_KEY" \
-X GET "https://api.ayrshare.com/api/ads/facebook/insights?level=campaign&ids=120200000000000001&startDate=2026-09-01&endDate=2026-09-02"
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/facebook/insights?${params}`, {
method: "GET",
headers: { Authorization: `Bearer ${API_KEY}` },
})
.then((res) => res.json())
.then((json) => console.log(json))
.catch(console.error);
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/facebook/insights', headers=headers, params=params)
print(r.json())
{
"status": "success",
"platform": "facebook",
"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
}
{
"status": "success",
"platform": "facebook",
"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
}
{
"action": "ads",
"status": "error",
"code": 400,
"message": "The ad is not found or not authorized."
}