Prompts
As perguntas enviadas aos modelos de IA segundo a cadência de monitorização configurada na conta, com os registos correspondentes a cada execução.
GET/dimensions/prompts
Lista os Prompts de um projeto.
project_idobrigatóriomodelapenas os prompts com pelo menos uma execução nesse modelo, independentemente do resultado ou da datacollection_idpromptID do promptcountry_codelanguage_codefromtopageper_page≤100
Tanto from como to filtram pela data de criação do prompt.
GET/dimensions/prompt_executions
Lista as execuções de prompts num projeto.
project_idobrigatóriomodelcollection_idpromptID do promptcountry_codelanguage_codeprompt_typebrand_kindfromtopageper_pagemention_filtercitation_filtercompetitorsa matriz de dois eixos descrita emGET /answers
GET/dimensions/query_fan_outs
As subconsultas que um modelo emitiu efetivamente ao responder aos seus Prompts monitorizados, útil para descobrir a formulação que os modelos pesquisam, em vez da formulação que escreveu. view=query (predefinido) devolve uma linha por subconsulta distinta, com a respetiva contagem e percentagem de todas as ocorrências; view=prompt devolve uma linha por prompt, com o número de subconsultas distintas que produziu. O Query Fan Out é comunicado sobretudo pelo ChatGPT, pelo que um resultado vazio significa normalmente que os modelos abrangidos não o expõem.
project_idobrigatórioviewqueryoupromptquerysubcadeia no texto da subconsultaorderdirectionmodelcollection_idpromptcountry_codelanguage_codeprompt_typebrand_kindrangefromtopageper_pageoutput
GET/suggested_prompts
A fila Prompts sugeridos, a mesma lista do separador Prompts sugeridos da aplicação: as sugestões de todos os geradores, da mais antiga para a mais recente e, por predefinição, apenas as pendentes.
project_idobrigatóriosourcewebsite,magic,topic,reddit,paa,reputational,translate,gscoucatalogstatuspending,accepted,rejectedouallpageper_page≤100, predefinição 50
GET/prompt_generations/:id
Consulte periodicamente uma execução de sugestões até o estado ser completed (com as sugestões que guardou) ou failed (com um código e uma mensagem de erro). A maioria das execuções termina em menos de um minuto. As execuções são mantidas durante 24 horas; as respetivas sugestões permanecem na fila.
project_idobrigatório:ido id da execução, no URL
POST/prompts
Crie até 100 Prompts por pedido. Os Prompts existentes (mesmo texto + idioma) são ignorados.
project_idobrigatóriopromptsarray, obrigatório, máx. 100country_codeobrigatóriolanguage_codeobrigatório
POST/prompts/import
A importação CSV da aplicação, em JSON. Cada linha tem país, idioma e etiquetas próprios. As etiquetas que ainda não existem são criadas, e os prompts duplicados são ignorados, mas recebem na mesma as etiquetas da linha; se os novos prompts excederem o limite do plano, nada é importado. Uma linha é ignorada e devolvida em row_errors quando o país ou o idioma da linha não é reconhecido, quando um prompt ficaria com mais de 50 etiquetas (somam-se as etiquetas de todas as linhas que repetem o mesmo prompt) ou quando as respetivas etiquetas levariam o pedido a ultrapassar as 500 etiquetas novas. Um membro da equipa precisa de acesso de criação a Etiquetas para criar uma etiqueta (sem esse acesso, uma linha que precise de uma etiqueta nova é ignorada e devolvida em row_errors) e de acesso de atualização a Prompts para atribuir etiquetas a um prompt que já existia (sem esse acesso, a linha não adiciona etiquetas a esse prompt e é devolvida em row_errors quando teria adicionado pelo menos uma). Requer uma chave de API com permissão de escrita e, para os membros da equipa, acesso de criação a Prompts.
- Corpo (JSON):
project_id(obrigatório),rows(array obrigatório, máx. 500) comprompt(obrigatório),country_code,language_code(códigos ou nomes; predefinição: os do projeto) etags(array de nomes).
POST/prompt_generations
Inicia uma execução de sugestões de prompts com um dos geradores por trás dos assistentes Adicionar prompts da aplicação. A execução responde com 202 e decorre em segundo plano; as respetivas sugestões chegam à fila Prompts sugeridos e nada é monitorizado até as aceitar. Requer uma chave de API com permissão de escrita.
- Corpo (JSON):
project_id(obrigatório),source(obrigatório:website,keyword,topic,reddit,paa,reputational,translateousearch_console),country_codeelanguage_code(predefinição: os do projeto). Por origem:query(opcional em keyword; obrigatório em topic e reddit),count(keyword e topic, 1-100, predefinição 20),competitor_id(keyword),search_type(reddit:topicoubrand),keywords(paa, até 5),source_country_codeesource_language_code(translate),min_wordseall_countries(search_console, plano Growth ou superior).
POST /suggested_prompts/accept + /reject
Aceita sugestões pendentes para as monitorizar como prompts, cada uma com o respetivo país e idioma e, opcionalmente, numa etiqueta, ou rejeita-as para que saiam da lista de pendentes. Quando os novos prompts excederiam o limite de prompts do plano, nada é aceite (ERR_LIMIT_REACHED). Requer uma chave de API com permissão de escrita.
project_idobrigatórioidsarray obrigatório, máx. 100
Em accept, também pode indicar uma etiqueta através de tag_ids ou tag_names, e create_missing (bool).
PATCH/prompts/:id
Define manualmente a intenção de pesquisa (prompt_type) e/ou o foco de marca (brand_kind) de um prompt, exatamente como quando edita os respetivos distintivos na página do prompt. O prompt fica marcado como categorizado manualmente (categorization_source passa a manual), pelo que a categorização automática deixa de o alterar; na página do prompt, é possível voltar à categorização automática. Não disponível a partir de um portal de marca branca (ERR_INTEGRATION_UNAVAILABLE). Requer uma chave de API com âmbito de escrita e, para os membros da equipa, a permissão de atualização em Prompts. Também disponível como a ferramenta MCP update_prompt_categorization.
:idid do prompt
Corpo (JSON): project_id (obrigatório), prompt_type (informational|navigational|commercial|transactional), brand_kind (brand|brand_other|non_brand); pelo menos um dos dois. Qualquer outro campo, ou um valor desconhecido, devolve ERR_INVALID_PARAM.
DELETE/prompts/:id
Elimina um prompt. Irreversível; o prompt desaparece imediatamente, liberta uma vaga de prompt e o seu histórico (execuções, menções, citações e sentimento) é eliminado por uma tarefa em segundo plano. Requer uma chave de API com permissão de escrita.
project_idobrigatório:idno URL
Devolve ERR_NOT_FOUND para prompts fora do projeto.