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
Create 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."
}
}
Adds a new tracking prompt to a project. Finseo will run this prompt on the project’s AI models and record visibility for your brand vs competitors across ChatGPT, Claude, Perplexity and the other enabled models.
The prompt is queued for processing immediately (
enqueued: true in the response); first answers typically arrive within a few minutes. The prompt inherits the project’s domain, brand name, synonyms, domain aliases and tracking frequency — the project therefore needs a websiteUrl, otherwise the request is rejected with 400.
string
required
Project identifier.
string
required
Prompt text (1–500 characters).
array
Optional. Defaults to the project’s enabled models (the dashboard’s Model
Settings, returned as
models by Get Project).
When given, it must be a subset of those — a prompt cannot run on a model
the project has not enabled, otherwise the dashboard filters and the prompt
data would disagree. Enable models for the project first via
Update Project. A model outside the
enabled set is rejected with 400 and a message starting with
model_not_enabled.string
Language / market code for the prompt (e.g.
de, en). Defaults to the
project’s language. The value is normalised to the dashboard’s spelling
(de → DE) so the country filter matches.array
Optional string tags for filtering in analytics.
Pitch projects (
isPitch: true) are limited to 50 prompts. Adding
prompts to an expired pitch project is rejected — convert it to a client
project first via Update Project.Errors
The same limits apply as when adding a prompt in the dashboard. Violations return403 with error.code = "FORBIDDEN" and error.details.reason:
details.reason | Meaning |
|---|---|
prompt_limit | Prompt cap of your plan reached (promptsUsed, promptLimit). |
prompt_budget_exceeded | Brand plan: this prompt on these models would exceed the prompt budget (promptLimit, slotsUsed, projectedSlots). |
agency_limit | Agency: projected monthly answers exceed the included band and a higher package exists (package, nextPackage, includedResults, projectedMonthlyAnswers). The top package is never blocked; the excess is billed as overage. |
pitch_prompt_limit | Pitch project already has 50 prompts (current, limit). |
pitch_expired | The pitch window has closed; convert the project first. |
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."
}
}