curl --request POST \
--url https://api.finseo.ai/v1/projects/67a1c2d3e4f5061728394a5b/prompts \
--header "Authorization: Bearer $FINSEO_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"prompt": "How does Finseo compare to traditional SEO suites?",
"language": "en",
"tags": ["comparison", "Finseo"]
}'
import requests
payload = {
"prompt": "How does Finseo compare to traditional SEO suites?",
"language": "en",
"tags": ["comparison", "Finseo"],
}
r = requests.post(
"https://api.finseo.ai/v1/projects/67a1c2d3e4f5061728394a5b/prompts",
headers={"Authorization": "Bearer sk_live_xxxxxxxx"},
json=payload,
)
print(r.json()["data"])
{
"data": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"prompt": "How does Finseo compare to traditional SEO suites?",
"domain": "https://www.finseo.ai",
"brand_name": "Finseo",
"language": "EN",
"models": ["chatgpt", "perplexity", "ai_overview"],
"tags": ["comparison", "Finseo"],
"project_id": "67a1c2d3e4f5061728394a5b",
"active": true,
"processing_complete": false,
"created_at": "2026-09-10T09:41:12.481Z",
"enqueued": true
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "model_not_enabled: mistral is not enabled for this project (enabled: chatgpt, perplexity, ai_overview). Enable it via PUT /v1/projects/{projectId} with \"models\", or omit \"models\" to use the project settings."
}
}
Prompts
Criar Prompt
POST
/
v1
/
projects
/
{projectId}
/
prompts
curl --request POST \
--url https://api.finseo.ai/v1/projects/67a1c2d3e4f5061728394a5b/prompts \
--header "Authorization: Bearer $FINSEO_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"prompt": "How does Finseo compare to traditional SEO suites?",
"language": "en",
"tags": ["comparison", "Finseo"]
}'
import requests
payload = {
"prompt": "How does Finseo compare to traditional SEO suites?",
"language": "en",
"tags": ["comparison", "Finseo"],
}
r = requests.post(
"https://api.finseo.ai/v1/projects/67a1c2d3e4f5061728394a5b/prompts",
headers={"Authorization": "Bearer sk_live_xxxxxxxx"},
json=payload,
)
print(r.json()["data"])
{
"data": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"prompt": "How does Finseo compare to traditional SEO suites?",
"domain": "https://www.finseo.ai",
"brand_name": "Finseo",
"language": "EN",
"models": ["chatgpt", "perplexity", "ai_overview"],
"tags": ["comparison", "Finseo"],
"project_id": "67a1c2d3e4f5061728394a5b",
"active": true,
"processing_complete": false,
"created_at": "2026-09-10T09:41:12.481Z",
"enqueued": true
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "model_not_enabled: mistral is not enabled for this project (enabled: chatgpt, perplexity, ai_overview). Enable it via PUT /v1/projects/{projectId} with \"models\", or omit \"models\" to use the project settings."
}
}
Adiciona um novo Prompt de Tracking a um projeto. A Finseo executará este Prompt nos modelos de IA do projeto e registrará a visibilidade da sua marca em comparação com os concorrentes no ChatGPT, Claude, Perplexity e nos demais modelos habilitados.
O Prompt é colocado na fila de processamento imediatamente (
enqueued: true na resposta); as primeiras respostas costumam chegar em poucos minutos. O Prompt herda o domínio, o nome da marca, os sinônimos, os aliases de domínio e a frequência de Tracking do projeto — por isso o projeto precisa de uma websiteUrl, caso contrário a solicitação é rejeitada com 400.
string
obrigatório
Identificador do projeto.
string
obrigatório
Texto do Prompt (1–500 caracteres).
array
Opcional. O padrão são os modelos habilitados do projeto (as Configurações de
modelos do dashboard, retornadas como
models por Obter projeto).
Quando informado, deve ser um subconjunto deles — um Prompt não pode ser
executado em um modelo que o projeto não habilitou, caso contrário os filtros do
dashboard e os dados do Prompt ficariam inconsistentes. Habilite primeiro os
modelos do projeto por meio de Atualizar projeto.
Um modelo fora do conjunto habilitado é rejeitado com 400 e uma mensagem que
começa com model_not_enabled.string
Código de idioma/mercado do Prompt (ex.:
de, en). O padrão é o language do projeto. O valor é normalizado para a grafia do dashboard (de → DE) para que o filtro de país corresponda.array
Tags de texto opcionais para filtragem nas análises.
Projetos de pitch (
isPitch: true) são limitados a 50 prompts. A inclusão de prompts em um pitch expirado é rejeitada; converta-o primeiro em projeto de cliente por meio de Atualizar projeto.Erros
Aplicam-se os mesmos limites de quando um Prompt é adicionado no dashboard. Violações retornam403 com error.code = "FORBIDDEN" e error.details.reason:
details.reason | Significado |
|---|---|
prompt_limit | Limite de prompts do seu plano atingido (promptsUsed, promptLimit). |
prompt_budget_exceeded | Plano Brand: este Prompt nestes modelos excederia o orçamento de prompts (promptLimit, slotsUsed, projectedSlots). |
agency_limit | Agency: as respostas mensais projetadas excedem a faixa incluída e existe um pacote superior (package, nextPackage, includedResults, projectedMonthlyAnswers). O pacote mais alto nunca é bloqueado; o excedente é cobrado como consumo adicional. |
pitch_prompt_limit | O projeto de pitch já tem 50 prompts (current, limit). |
pitch_expired | A janela do pitch foi encerrada; converta o projeto primeiro. |
curl --request POST \
--url https://api.finseo.ai/v1/projects/67a1c2d3e4f5061728394a5b/prompts \
--header "Authorization: Bearer $FINSEO_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"prompt": "How does Finseo compare to traditional SEO suites?",
"language": "en",
"tags": ["comparison", "Finseo"]
}'
import requests
payload = {
"prompt": "How does Finseo compare to traditional SEO suites?",
"language": "en",
"tags": ["comparison", "Finseo"],
}
r = requests.post(
"https://api.finseo.ai/v1/projects/67a1c2d3e4f5061728394a5b/prompts",
headers={"Authorization": "Bearer sk_live_xxxxxxxx"},
json=payload,
)
print(r.json()["data"])
{
"data": {
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"prompt": "How does Finseo compare to traditional SEO suites?",
"domain": "https://www.finseo.ai",
"brand_name": "Finseo",
"language": "EN",
"models": ["chatgpt", "perplexity", "ai_overview"],
"tags": ["comparison", "Finseo"],
"project_id": "67a1c2d3e4f5061728394a5b",
"active": true,
"processing_complete": false,
"created_at": "2026-09-10T09:41:12.481Z",
"enqueued": true
}
}
{
"error": {
"code": "VALIDATION_ERROR",
"message": "model_not_enabled: mistral is not enabled for this project (enabled: chatgpt, perplexity, ai_overview). Enable it via PUT /v1/projects/{projectId} with \"models\", or omit \"models\" to use the project settings."
}
}