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
Obter insights diários em tempo real de anúncios do Facebook por campanha ou anúncio
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."
}
Obtenha o desempenho em tempo real dos seus anúncios do Facebook, 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.
O Facebook informa todas as métricas desta tabela. Uma exceção: a Meta não informa
- Os números são lidos da Meta no momento da chamada, e não de uma cópia noturna.
- Use o Histórico para o gasto que cobramos. Use os Insights para relatórios e análises.
- Todos os valores monetários estão na moeda da conta de anúncios, retornada em
currencyem cada linha. - 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.
- 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.
Parâmetros de cabeçalho
Parâmetros de consulta
string
obrigatório
Sobre o que cada linha informa:
campaign ou ad.adSet ainda não é suportado e retorna o código 101.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.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.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.string
padrão:"30 dias atrás"
Primeiro dia, no formato
YYYY-MM-DD. Pode ser de até 37 meses atrás.string
padrão:"hoje"
Último dia, no formato
YYYY-MM-DD.string
O
nextCursor da resposta anterior, para obter a próxima página.Métricas
| 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 |
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.
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.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 |
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."
}