API

Prompts

The Prompts API manages the prompts sent to AI models inside a project and exposes the results those models return. Prompts are grouped under topics. Each prompt is run against the project’s AI models, and every run produces a result containing the model’s text, the brands and URLs it mentioned, the sentiment, and an average position.

Using the SE Visible API, you can:

list project’s prompts with their visibility metrics, or list topics with aggregated metrics
create prompts under a topic and delete prompts in bulk
move prompts to another topic
read the details of a single prompt
list the results for a prompt and read a single result in detail

All endpoints are relative to the base URL https://api.seranking.com/v1/se-visible.

List prompts or topics

GET https://api.seranking.com/v1/se-visible/projects/{project_id}/prompts

Returns a paginated list of the project’s prompts with their visibility metrics, or a list of topics with metrics aggregated across their prompts. The group_mode parameter controls which of the two shapes the response takes.

Note:

group_mode=prompt (the default) returns individual prompts, one item per prompt.
group_mode=topic returns topics instead, with metrics aggregated across all prompts in each topic.
The response schema differs between the two modes. See both response examples below.

Request parameters

Path parameters

Parameter	Type	Required	Description
project_id	String (UUID)	Yes	UUID of the project.

Query parameters

Parameter	Type	Required	Default	Description
group_mode	String	No	`prompt`	What to list: `prompt` for individual prompts, `topic` for topics with aggregated metrics.
date_range	Object	Yes	N/A	Base period at index `0`, optional compare period at index `1`. Each has `from` and `to` in `YYYY-MM-DD`. See Date ranges and compare mode.
model_types	Array of String	No	N/A	Filter by AI model types (e.g. `chatgpt`, `perplexity`). See the Reference for the full list.
country_codes	Array of String	No	N/A	Filter by ISO 3166-1 alpha-2 country codes. See the Reference for the full list.
topic_ids	Array of Integer	No	N/A	Filter by topic IDs.
search_query	String	No	N/A	Filter prompts by a search string.
limit	Integer	No	`1000`	Maximum number of items to return.
offset	Integer	No	`0`	Number of items to skip from the start of the list.
sort_field	String	No	`visibility`	Field to sort by: `id`, `visibility`, `avg_position`, `mentions`, `sentiments`, `sov`, `rank`, `visibility_delta`, `avg_position_delta`, `sentiments_delta`, `sov_delta`. See the note below.
sort_order	String	No	`desc`	Sort direction: `asc` or `desc`.
sentiments	Array of String	No	N/A	Filter by sentiment: `positive`, `neutral`, `negative`.
tracked_brand_ids	Array of Integer	No	N/A	Filter by tracked brand IDs.

Note: the *_delta sort variants sort by the absolute change between periods. They require date_range[1] to be present and to contain checks, otherwise the request is rejected with 422. id sorts by prompt (or topic) ID. rank is accepted but currently falls back to the default visibility ordering.

Request example

Copy

curl -X GET --globoff 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/prompts?group_mode=prompt&date_range[0][from]=2026-05-01&date_range[0][to]=2026-05-31' \

  -H 'Authorization: Token YOUR_API_KEY'

To include a comparison period (adds delta to each metric in the response), pass a second date_range entry:

Copy

curl -X GET --globoff 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/prompts?group_mode=prompt&date_range[0][from]=2026-05-23&date_range[0][to]=2026-08-20&date_range[1][from]=2026-02-22&date_range[1][to]=2026-05-22' \

  -H 'Authorization: Token YOUR_API_KEY'

The same comparison mode applies to group_mode=topic:

Copy

curl -X GET --globoff 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/prompts?group_mode=topic&date_range[0][from]=2026-05-23&date_range[0][to]=2026-08-20&date_range[1][from]=2026-02-22&date_range[1][to]=2026-05-22' \

  -H 'Authorization: Token YOUR_API_KEY'

Response parameters

If successful, the server returns a paginated object. The shape of each item in items depends on group_mode.

group_mode=prompt

Parameter	Type	Description
items	Array	Array of prompts.
items[].id	Integer	Prompt ID.
items[].topic_id	Integer	ID of the topic the prompt belongs to.
items[].prompt	String	Prompt text.
items[].mentions	Object	Number of mentions. See MetricValue.
items[].avg_position	Object	Average position across results. See MetricValue.
items[].sentiments	Object	Sentiment score, −100–100. See MetricValue.
items[].visibility	Object	Visibility score, 0–100. See MetricValue.
items[].sov	Object	Share of voice, 0–100. See MetricValue.
items[].organic_overlap	Object	Share of the organic top-20 links that also appear in the AI Overview block, as a percentage. Averaged only over queries where the AI Overview was shown; `values` is `null` when the block was never present. See MetricValue.
items[].search_intent	Array or null	Search intent codes (e.g. `["I"]`). `null` when not applicable.
items[].tops	Array	Top brands for this prompt (`brand_id`, `brand_name`).
items[].is_parsed	Boolean	Whether the prompt has been parsed.
total	Integer	Total number of prompts available.

MetricValue object

Each visibility metric (mentions, avg_position, sentiments, visibility, sov, organic_overlap) is returned as a MetricValue object rather than a plain number.

Parameter	Type	Description
values	Array	Metric values. One element per requested period: one value with no comparison, two values (base, compared) when a comparison period is supplied. Elements may be `null` when a period has no data.
delta	Object	Change between periods. Present only when a comparison period is requested.
delta.absolute	Float or null	Absolute change. `null` when it cannot be computed.
delta.percentage	Float or null	Percentage change. `null` when it cannot be computed.

Note: value ranges — sentiments is -100–100; visibility, sov, and organic_overlap are 0–100; mentions is a raw count; avg_position is a float.

Example — group_mode=prompt (default)

One row per prompt. Row-specific fields: id, topic_id, prompt, is_parsed.

Request example

Copy

curl -X GET --globoff 'https://api.seranking.com/v1/se-visible/projects/{project_id}/prompts?group_mode=prompt&date_range[0][from]=2026-05-23&date_range[0][to]=2026-08-20&date_range[1][from]=2026-02-22&date_range[1][to]=2026-05-22' \

  -H 'Authorization: Token YOUR_API_KEY'

Response example

Copy

{

  "total": 194,

  "items": [

    {

      "id": 477111,

      "topic_id": 112593,

      "prompt": "What are the best document automation software solutions for small businesses?",

      "mentions":        { "values": [187, 87],  "delta": { "absolute": 100,  "percentage": 114.9 } },

      "avg_position":    { "values": [1.4, 1.7], "delta": { "absolute": -0.3, "percentage": -17.6 } },

      "sentiments":      { "values": [77, 65],   "delta": { "absolute": 12,   "percentage": 18.5 } },

      "visibility":      { "values": [97, 97],   "delta": { "absolute": 0.5,  "percentage": 0.5 } },

      "sov":             { "values": [10, 8],    "delta": { "absolute": 1.5,  "percentage": 17.8 } },

      "organic_overlap": { "values": [35, 28],   "delta": { "absolute": 7,    "percentage": 25.0 } },

      "tops": [ { "brand_id": 6075, "brand_name": "Adobe creative cloud" } ],

      "is_parsed": true,

      "search_intent": ["I"]

    }

  ]

}

group_mode=topic

Parameter	Type	Description
items	Array	Array of topics with aggregated metrics.
items[].id	Integer	Topic ID.
items[].title	String	Topic title.
items[].prompts_count	Integer	Number of prompts in the topic.
items[].mentions	Object	Aggregated mentions across the topic’s prompts. See MetricValue.
items[].avg_position	Object	Aggregated average position across the topic’s prompts. See MetricValue.
items[].sentiments	Object	Aggregated sentiment score across the topic’s prompts, −100–100. See MetricValue.
items[].visibility	Object	Aggregated visibility score across the topic’s prompts, 0–100. See MetricValue.
items[].sov	Object	Aggregated share of voice across the topic’s prompts, 0–100. See MetricValue.
items[].organic_overlap	Object	Aggregated organic-to-AI-Overview link overlap across the topic’s prompts, as a percentage. Averaged only over queries where the AI Overview was shown; `values` is `null` when the block was never present. See MetricValue.
items[].search_intent	Array or null	Search intent codes (e.g. `["I"]`). `null` when not applicable.
items[].tops	Array	Top brands across the topic’s prompts (`brand_id`, `brand_name`).
total	Integer	Total number of topics available.

Example — group_mode=topic

One row per topic, metrics aggregated across the topic’s prompts. Row-specific fields: id, title, prompts_count (replacing topic_id, prompt, is_parsed). The metric objects are identical to prompt mode.

Request example

Copy

curl -X GET --globoff 'https://api.seranking.com/v1/se-visible/projects/{project_id}/prompts?group_mode=topic&date_range[0][from]=2026-05-23&date_range[0][to]=2026-08-20&date_range[1][from]=2026-02-22&date_range[1][to]=2026-05-22' \

  -H 'Authorization: Token YOUR_API_KEY'

Response example

Copy

{

  "total": 18,

  "items": [

    {

      "id": 61,

      "title": "On-Page SEO Checker",

      "prompts_count": 1,

      "mentions":        { "values": [191, 168], "delta": { "absolute": 23,  "percentage": 13.7 } },

      "avg_position":    { "values": [1, 1],     "delta": { "absolute": 0,   "percentage": 0 } },

      "sentiments":      { "values": [11, 5],    "delta": { "absolute": 6,   "percentage": 120 } },

      "visibility":      { "values": [100, 92],  "delta": { "absolute": 7.6, "percentage": 8.3 } },

      "sov":             { "values": [11, 9],    "delta": { "absolute": 1.9, "percentage": 21.1 } },

      "organic_overlap": { "values": [null, null] },

      "tops": [ { "brand_id": 1509, "brand_name": "Se ranking" } ],

      "search_intent": ["I"]

    }

  ]

}

Delete prompts

DELETE https://api.seranking.com/v1/se-visible/projects/{project_id}/prompts

Deletes one or more prompts from a project in a single request.

Request parameters

Path parameters

Parameter	Type	Required	Description
project_id	String (UUID)	Yes	UUID of the project.

Request body

Parameter	Type	Required	Description
prompt_ids	Array of Integer	Yes	IDs of the prompts to delete.

Request example

Copy

curl -X DELETE 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/prompts' \

  -H 'Authorization: Token YOUR_API_KEY' \

  -H 'Content-Type: application/json' \

  -d '{

    "prompt_ids": [1, 2]

  }'

Response parameters

If successful, the server returns 204 No Content with an empty body.

Create prompts for a topic

POST https://api.seranking.com/v1/se-visible/projects/{project_id}/topics/{topic_id}/prompts

Creates one or more prompts under a topic. The prompts are added to the topic identified by topic_id and start being processed against the project’s AI models.

Request parameters

Path parameters

Parameter	Type	Required	Description
project_id	String (UUID)	Yes	UUID of the project.
topic_id	Integer	Yes	ID of the topic the prompts are created under.

Request body

Parameter	Type	Required	Description
prompts	Array of String	Yes	Prompt texts to create.

Request example

Copy

curl -X POST 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/topics/10/prompts' \

  -H 'Authorization: Token YOUR_API_KEY' \

  -H 'Content-Type: application/json' \

  -d '{

    "prompts": [

      "What are the benefits of using artificial intelligence in healthcare?",

      "How does AI improve patient diagnosis?"

    ]

  }'

Response parameters

If successful, the server returns 201 with a JSON array of the created prompt IDs.

Parameter	Type	Description
[]	Integer	ID of a created prompt.

Response example

Copy

[7, 40]

Move prompts to a topic

POST https://api.seranking.com/v1/se-visible/projects/{project_id}/prompts/move/{topic_id}

Moves prompts to the target topic identified by topic_id. Select the prompts to move by their IDs, by their source topics, or both.

Note:

At least one of prompt_ids or topic_ids must be provided.
When topic_ids is supplied, all prompts belonging to those topics are moved.
Both fields can be combined; the resulting set is deduplicated.
The operation is atomic (all-or-nothing), and the target topic must belong to the same project.

Request parameters

Path parameters

Parameter	Type	Required	Description
project_id	String (UUID)	Yes	UUID of the project.
topic_id	Integer	Yes	ID of the target topic the prompts are moved to.

Request body

Parameter	Type	Required	Description
prompt_ids	Array of Integer	No	IDs of individual prompts to move.
topic_ids	Array of Integer	No	IDs of source topics whose prompts should all be moved.

Request example

Copy

curl -X POST 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/prompts/move/12' \

  -H 'Authorization: Token YOUR_API_KEY' \

  -H 'Content-Type: application/json' \

  -d '{

    "prompt_ids": [1, 2],

    "topic_ids": [10]

  }'

Response parameters

If successful, the server returns 204 No Content with an empty body.

Get prompt details

GET https://api.seranking.com/v1/se-visible/projects/{project_id}/prompts/{prompt_id}

Returns the details of a single prompt.

Request parameters

Path parameters

Parameter	Type	Required	Description
project_id	String (UUID)	Yes	UUID of the project.
prompt_id	Integer	Yes	ID of the prompt.

Request example

Copy

curl -X GET 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/prompts/1' \

  -H 'Authorization: Token YOUR_API_KEY'

Response parameters

If successful, the server returns the prompt object.

Parameter	Type	Description
id	Integer	Prompt ID.
text	String	Prompt text.
topic_id	Integer	ID of the topic the prompt belongs to.
report_id	String (UUID)	Project the prompt belongs to.
created_at	String	When the prompt was created, as an ISO 8601 timestamp.
text_hash	Integer	Server-generated checksum of `text`. Read-only.
deleted_at	String or null	Deletion timestamp. Always `null` for a prompt this endpoint can return.
is_parsed	Boolean	Whether the prompt has been parsed.

Response example

Copy

{

  "id": 1,

  "text": "What are the best ground coffee brands for a rich and smooth flavor?",

  "topic_id": 10,

  "report_id": "550e8400-e29b-41d4-a716-446655440000",

  "created_at": "2023-12-15T10:30:00.000000Z",

  "text_hash": 2751880790,

  "deleted_at": null,

  "is_parsed": true

}

Get prompt result list

GET https://api.seranking.com/v1/se-visible/projects/{project_id}/prompts/{prompt_id}/results

Returns a paginated list of results for a prompt. Each result is one model run, with the model’s text, the brands it mentioned, sentiment, and an average position.

Request parameters

Path parameters

Parameter	Type	Required	Description
project_id	String (UUID)	Yes	UUID of the project.
prompt_id	Integer	Yes	ID of the prompt.

Query parameters

Parameter	Type	Required	Default	Description
date_range	Object	Yes	N/A	Base period at index `0`, optional compare period at index `1`. Each has `from` and `to` in `YYYY-MM-DD`. See Date ranges and compare mode.
model_types	Array of String	No	N/A	Filter by AI model types (e.g. `chatgpt`, `perplexity`). See the Reference for the full list.
country_codes	Array of String	No	N/A	Filter by ISO 3166-1 alpha-2 country codes. See the Reference for the full list.
sentiments	Array of String	No	N/A	Filter by sentiment: `positive`, `neutral`, `negative`.
limit	Integer	No	`1000`	Maximum number of items to return.
offset	Integer	No	`0`	Number of items to skip from the start of the list.

Note: topic_ids and tracked_brand_ids are no longer part of this endpoint’s contract. They were previously accepted but never applied, so removing them changes no response. If your integration passed them here, the data you received was unfiltered — please re-check it. They remain valid on List prompts or topics and on the brand metrics endpoint, where they are applied.

Request example

Copy

curl -X GET --globoff 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/prompts/1/results?date_range[0][from]=2026-05-01&date_range[0][to]=2026-05-31' \

  -H 'Authorization: Token YOUR_API_KEY'

Response parameters

If successful, the server returns a paginated object of results.

Parameter	Type	Description
items	Array	Array of results.
items[].id	Integer	Result ID.
items[].prompt	String	Prompt text.
items[].request_number	Integer	Request number for this prompt run.
items[].avg_position	Float	Average position in the result.
items[].sentiment	String or null	Sentiment: `positive`, `neutral`, `negative`, or `null`.
items[].text	String	The AI-generated response text.
items[].has_urls	Boolean	Whether the result contains source URLs.
items[].tops	Array	Top brands mentioned (`brand_id`, `brand_name`).
items[].created_at	String	When the result was created (`YYYY-MM-DD HH:MM:SS`).
items[].has_mentions	Boolean	Whether the result has brand mentions.
items[].model	String	AI model that produced the result: `chatgpt`, `google_gemini`, `perplexity`, `google_ai_mode`, `google_ai_overview`.
total	Integer	Total number of results available.

Response example

Copy

{

  "items": [

    {

      "id": 101,

      "prompt": "What are the best ground coffee brands for a rich and smooth flavor?",

      "request_number": 1,

      "avg_position": 1.5,

      "sentiment": "positive",

      "text": "Based on extensive research and customer reviews, some of the best ground coffee brands...",

      "has_urls": true,

      "tops": [

        { "brand_id": 1, "brand_name": "Lavazza" },

        { "brand_id": 2, "brand_name": "Illy" },

        { "brand_id": 3, "brand_name": "Starbucks" }

      ],

      "created_at": "2023-12-15 10:30:00",

      "has_mentions": true,

      "model": "chatgpt"

    },

    {

      "id": 102,

      "prompt": "What are the best ground coffee brands for a rich and smooth flavor?",

      "request_number": 2,

      "avg_position": 2.3,

      "sentiment": "neutral",

      "text": "Coffee preferences vary greatly among consumers, but several brands consistently...",

      "has_urls": false,

      "tops": [

        { "brand_id": 4, "brand_name": "Folgers" },

        { "brand_id": 5, "brand_name": "Maxwell House" },

        { "brand_id": 6, "brand_name": "Dunkin'" }

      ],

      "created_at": "2023-12-15 10:35:00",

      "has_mentions": true,

      "model": "google_gemini"

    }

  ],

  "total": 25

}

Get prompt result details

GET https://api.seranking.com/v1/se-visible/projects/{project_id}/prompts/{prompt_id}/results/{result_id}

Returns the full detail of a single result, including the complete response text, the source URLs, and the brands mentioned.

Request parameters

Path parameters

Parameter	Type	Required	Description
project_id	String (UUID)	Yes	UUID of the project.
prompt_id	Integer	Yes	ID of the prompt.
result_id	Integer	Yes	ID of the result.

Request example

Copy

curl -X GET 'https://api.seranking.com/v1/se-visible/projects/550e8400-e29b-41d4-a716-446655440000/prompts/1/results/101' \

  -H 'Authorization: Token YOUR_API_KEY'

Response parameters

If successful, the server returns the result object.

Parameter	Type	Description
id	Integer	Result ID.
prompt	String	Prompt text.
request_number	Integer	Request number for this prompt run.
avg_position	Float	Average position in the result.
sentiment	String or null	Sentiment: `positive`, `neutral`, `negative`, or `null`.
text	String	The AI-generated response text.
urls	Array of String	Source URLs mentioned in the result.
brands	Array	Brands mentioned in the result (`brand_id`, `brand_name`).
created_at	String	When the result was created (`YYYY-MM-DD HH:MM:SS`).
has_mentions	Boolean	Whether the result has brand mentions.
model	String	AI model that produced the result: `chatgpt`, `google_gemini`, `perplexity`, `google_ai_mode`, `google_ai_overview`.

Response example

Copy

{

  "id": 101,

  "prompt": "What are the best ground coffee brands for a rich and smooth flavor?",

  "request_number": 1,

  "avg_position": 1.5,

  "sentiment": "positive",

  "text": "Based on extensive research and customer reviews, some of the best ground coffee brands for rich and smooth flavor include Lavazza, known for its Italian roasting expertise and premium blends...",

  "urls": [

    "https://example.com/coffee-review",

    "https://coffeeblog.com/best-brands"

  ],

  "brands": [

    { "brand_id": 1, "brand_name": "Lavazza" },

    { "brand_id": 2, "brand_name": "Illy" },

    { "brand_id": 3, "brand_name": "Starbucks" }

  ],

  "created_at": "2023-12-15 10:30:00",

  "has_mentions": true,

  "model": "chatgpt"

}

Prompts

List prompts or topics

Request parameters

Request example

Response parameters

MetricValue object

Example — group_mode=prompt (default)

Request example

Response example

Example — group_mode=topic

Request example

Response example

Delete prompts

Request parameters

Request example

Response parameters

Create prompts for a topic

Request parameters

Request example

Response parameters

Response example

Move prompts to a topic

Request parameters

Request example

Response parameters

Get prompt details

Request parameters

Request example

Response parameters

Response example

Get prompt result list

Request parameters

Request example

Response parameters

Response example

Get prompt result details

Request parameters

Request example

Response parameters

Response example

Learn how SE Ranking’s API can boost your SEO!

Request a free demo to see our tools and integrations in action