Ads

Lister campagnes, ensembles et annonces Meta Ads via l'API

Trois routes GET listent les campagnes, ensembles et annonces du compte publicitaire d'un client, avec statut, statut effectif, problèmes et budget. Vous choisissez de lire ce que Connect stocke ou le compte en direct, sans OAuth à développer ni app review Meta.

L'appel

GET /api/ads/campaigns?customer_integration=<connection uuid>&source=external&status=active&per_page=50
Authorization: Bearer <merchant token>
x-customer-token: <customer token>

Ce que vous pouvez faire

  • Lister campagnes, ensembles d'annonces et annonces avec GET /ads/campaigns, /ads/adsets et /ads.
  • Lire le compte en direct avec source=external, y compris ce qui a été créé hors de Connect.
  • Filtrer par status (active ou paused) et, avec source=connect, par effective_status, comme pending_review ou disapproved.
  • Voir dans issues pourquoi la plateforme retient un objet, comme un refus ou un problème de diffusion.
  • Filtrer ensembles et annonces par campaign_id et annonces par adset_id, et paginer avec page et per_page.

Règles et limites

  • La valeur par défaut est source=connect : ce que Connect a créé ou déjà écrit dans le compte, sans appeler la plateforme. Un compte avec d'anciennes campagnes liste vide jusqu'à la première écriture via Connect.
  • Pour voir tout le compte, utilisez source=external. La lecture en direct est mise en cache 120 s, et refresh=true ignore le cache.
  • Chaque réponse contient synced_at, la dernière vérification de l'objet par Connect. Avec source=connect, refresh=true relit statut et nom des éléments de la page.
  • per_page va de 1 à 100 (15 par défaut) et la réponse est {data, links, meta}. Avec source=external, pas de meta.total, et avec status la page peut dépasser un peu per_page.
  • Les éléments stockés par Connect ont un uuid. Ceux qui n'existent que dans le compte ont uuid null. Le budget est dans la devise du compte, jamais en centimes.

Champs principaux

ChampTypeObligatoireDescription
customer_integrationstringOuiL'uuid de la connexion du client. Il définit le compte publicitaire. Toujours dans la query.
sourcestringNonconnect (par défaut) lit ce que Connect a créé ou déjà écrit dans le compte. external lit le compte en direct, y compris ce qui a été créé hors de Connect.
statusstringNonFiltre par active ou paused.
effective_statusstringNonUniquement avec source=connect. Filtre par le statut réellement appliqué par la plateforme, comme pending_review, disapproved ou with_issues.
refreshbooleanNonAvec source=external, ignore le cache de 120 s. Avec source=connect, relit statut et nom des éléments de la page et met Connect à jour.
per_pageintegerNonÉléments par page, de 1 à 100. La valeur par défaut est 15.
campaign_idstringNonUniquement sur /ads/adsets et /ads : filtre par l'id de la campagne ou l'uuid Connect.
include_deletedbooleanNonUniquement avec source=connect. Inclut les objets supprimés, avec deleted_at.

Pour qui

  • Tableau de bord de campagnes dans votre SaaS

    Montrez au client ses campagnes actives, le budget et le statut effectif sans qu'il ouvre le Gestionnaire de publicités.

  • Alerte d'annonce refusée

    Interrogez régulièrement avec effective_status=disapproved et prévenez l'équipe quand une annonce est refusée, avec le motif dans issues.

  • Agent IA qui audite les comptes

    Un agent liste le compte en direct, repère les ensembles avec des problèmes de diffusion et propose de mettre en pause ou d'ajuster le budget.

Fonctionne avec

  • Meta Ads

Questions fréquentes

Pourquoi la liste est-elle vide sur un compte qui avait déjà des campagnes ?

Parce que la valeur par défaut est source=connect, qui ne montre que ce que Connect a créé ou déjà écrit dans le compte. Pour voir ce qui a été créé hors de Connect, utilisez source=external.

Les données sont-elles en temps réel ?

Avec source=external oui, avec un cache de 120 s que refresh=true ignore. Avec source=connect, vous voyez le dernier état connu, indiqué dans synced_at, et refresh=true le met à jour.

Comment filtrer uniquement ce qui pose problème ?

Utilisez effective_status avec des valeurs comme with_issues, disapproved ou pending_review (uniquement avec source=connect). Le motif est dans le champ issues.

Voir aussi

Voir tout ce que vous pouvez faire avec Ads

Voyez Connect appliqué à votre produit.

Essayez-le pendant 15 jours sans carte, ou présentez votre cas à notre équipe.