Prompts
Les questions que nous posons aux modèles d’IA à la fréquence de suivi configurée pour le compte, et les enregistrements produits à chaque exécution.
GET/dimensions/prompts
Liste les prompts d’un projet.
- Paramètres :
project_id(obligatoire),model(uniquement les prompts ayant au moins une exécution sur ce modèle, quels qu’en soient le résultat et la date),collection_id,prompt(ID du prompt),country_code,language_code,from,to,page,per_page(≤100).fromettofiltrent tous deux sur la date de création du prompt.
GET/dimensions/prompt_executions
Liste les exécutions de prompts d’un projet.
project_idobligatoiremodelcollection_idpromptID du promptcountry_codelanguage_codeprompt_typebrand_kindfromtopageper_pagemention_filtercitation_filtercompetitorsla matrice à deux axes décrite pourGET /answers
GET/dimensions/query_fan_outs
Renvoie les sous-requêtes réellement émises par un modèle pour répondre à vos prompts suivis. Utile pour repérer les formulations que les modèles recherchent, plutôt que celles que vous avez rédigées. view=query (par défaut) renvoie une ligne par sous-requête distincte, avec son nombre d’occurrences et sa part du total des occurrences ; view=prompt renvoie une ligne par prompt, avec le nombre de sous-requêtes distinctes qu’il a produites. Ces sous-requêtes sont surtout fournies par ChatGPT : un résultat vide signifie généralement que les modèles concernés ne les exposent pas.
project_idobligatoireviewqueryoupromptquerysous-chaîne recherchée dans le texte de la sous-requêteorderdirectionmodelcollection_idpromptcountry_codelanguage_codeprompt_typebrand_kindrangefromtopageper_pageoutput
GET/suggested_prompts
La file Prompts suggérés, la même liste que l’onglet Prompts suggérés de l’application : les suggestions de tous les générateurs, des plus anciennes aux plus récentes, en attente par défaut.
project_idobligatoiresourcewebsite,magic,topic,reddit,paa,reputational,translate,gscoucatalogstatuspending,accepted,rejectedouallpageper_page≤100, 50 par défaut
GET/prompt_generations/:id
Interrogez régulièrement une exécution de suggestions jusqu’à ce que son statut soit completed (avec les suggestions enregistrées) ou failed (avec un code et un message d’erreur). La plupart des exécutions se terminent en moins d’une minute. Les exécutions sont conservées 24 heures ; leurs suggestions restent dans la file.
project_idobligatoire:idID de l’exécution, dans l’URL
POST/prompts
Crée jusqu’à 100 prompts par requête. Les prompts existants (même texte, même pays et même langue) sont ignorés.
project_idobligatoirepromptstableau, obligatoire, 100 au maximumcountry_codeobligatoirelanguage_codeobligatoire
POST/prompts/import
L’import CSV de l’application, au format JSON. Chaque ligne porte son propre pays, sa langue et ses tags. Les tags manquants sont créés, et les doublons sont ignorés mais reçoivent quand même les tags de la ligne ; si les nouveaux prompts dépassent la limite du forfait, rien n’est importé. Une ligne est ignorée et renvoyée dans row_errors quand son pays ou sa langue est inconnu, quand elle donnerait plus de 50 tags à un prompt (les lignes qui répètent un prompt s’additionnent) ou quand ses tags porteraient la requête au-delà de 500 nouveaux tags. Un membre de l’équipe a besoin de l’autorisation de création sur les tags pour créer un tag (sans elle, une ligne qui nécessite un nouveau tag est ignorée et renvoyée dans row_errors) et de l’autorisation de modification sur les prompts pour ajouter des tags à un prompt qui existait déjà (sans elle, la ligne n’ajoute aucun tag à ce prompt et est renvoyée dans row_errors lorsqu’elle en aurait ajouté un). Nécessite une clé API avec droit d’écriture et, pour les membres de l’équipe, l’autorisation de création sur les prompts.
- Corps (JSON) :
project_id(obligatoire),rows(tableau obligatoire, 500 lignes au maximum), chacune avecprompt(obligatoire),country_code,language_code(codes ou noms, ceux du projet par défaut) ettags(tableau de noms).
POST/prompt_generations
Lance une exécution de suggestions de prompts avec l’un des générateurs des assistants « Ajouter des prompts » de l’application. La requête répond 202 et l’exécution se poursuit en arrière-plan ; ses suggestions arrivent dans la file Prompts suggérés, et rien n’est suivi tant que vous ne les avez pas acceptées. Nécessite une clé API avec droit d’écriture.
- Corps (JSON) :
project_id(obligatoire),source(obligatoire :website,keyword,topic,reddit,paa,reputational,translateousearch_console),country_codeetlanguage_code(ceux du projet par défaut). Selon la source :query(facultatif pour keyword, obligatoire pour topic et reddit),count(keyword et topic, de 1 à 100, 20 par défaut),competitor_id(keyword),search_type(reddit :topicoubrand),keywords(paa, 5 au maximum),source_country_codeetsource_language_code(translate),min_wordsetall_countries(search_console, à partir du forfait Growth).
POST /suggested_prompts/accept + /reject
Accepte des suggestions en attente pour les suivre comme prompts, chacune dans son pays et sa langue et, si besoin, dans un tag, ou les refuse pour les retirer de la liste en attente. Si les nouveaux prompts dépassent la limite de prompts du forfait, rien n’est accepté (ERR_LIMIT_REACHED). Nécessite une clé API avec droit d’écriture.
project_idobligatoireidstableau obligatoire, 100 au maximum
L’endpoint accept prend aussi un tag via tag_ids ou tag_names, ainsi que create_missing (booléen).
PATCH/prompts/:id
Définit à la main, pour un prompt, l’intention de recherche (prompt_type) et/ou la marque dans le prompt (brand_kind), exactement comme en modifiant ses badges sur la page du prompt. Le prompt est marqué comme catégorisé manuellement (categorization_source devient manual) : la catégorisation automatique ne le modifie donc plus, et la page du prompt permet de revenir à la catégorisation automatique. Indisponible depuis un portail en marque blanche (ERR_INTEGRATION_UNAVAILABLE). Nécessite une clé API avec accès en écriture et, pour les membres de l’équipe, l’autorisation de modification sur les prompts. Également disponible via l’outil MCP update_prompt_categorization.
:idID du prompt
Corps (JSON) : project_id (obligatoire), prompt_type (informational|navigational|commercial|transactional), brand_kind (brand|brand_other|non_brand) ; au moins l’un des deux. Tout autre champ, ou une valeur inconnue, renvoie ERR_INVALID_PARAM.
DELETE/prompts/:id
Supprime un prompt. Action irréversible : le prompt disparaît immédiatement, libère une place dans le quota de prompts, et son historique (exécutions, mentions, citations, sentiment) est purgé par une tâche en arrière-plan. Nécessite une clé API avec accès en écriture.
project_idobligatoire:iddans l’URL
Renvoie ERR_NOT_FOUND pour les prompts hors du projet.