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	Array of Object	Yes	N/A	1 to 2 entries: 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`). See the Reference for the full list.
country_codes	Array of String	No	N/A	Deprecated — use `location_ids`. Filter by ISO 3166-1 alpha-2 country codes, resolved to the project’s live locations in those countries. It still works for now; migrate to `location_ids` before it is withdrawn. See the Reference for the full list.
location_ids	Array of String (UUID)	No	N/A	Filter by the project’s tracked locations, using location IDs from List project locations. Multiple values combine as OR. An ID of another project or of a deleted location is rejected with `422`. Combined with `country_codes`, only locations matching both are read.
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. Minimum 0; `0` returns an empty page.
offset	Integer	No	`0`	Number of items to skip from the start of the list. Minimum 0.
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`, `citations_count`, `citations_share`, `source_presence`, `source_presence_delta`, `organic_overlap`, `organic_overlap_delta`. See the note below.
sort_order	String	No	`asc`	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.
exclude_branded	Boolean	No	N/A	When `true`, every number in the response is computed from non-branded prompts only, and branded prompts drop out of the list. A prompt not classified yet counts as non-branded. Off when omitted.
search_intents	Array of String	No	N/A	Filter by search intent: `I` (informational), `L` (local), `N` (navigational), `C` (commercial), `T` (transactional). A prompt is returned when it carries any of the selected intents; prompts not classified yet are not returned while this filter is applied.
funnel_stages	Array of String	No	N/A	Filter by funnel stage: `awareness`, `consideration`, `decision`, `none`. A prompt is returned when it carries any of the selected stages. `none` matches only prompts explicitly marked as outside the funnel; prompts not classified yet are not returned while this filter is applied.
lang_codes	Array of String	No	N/A	Filter by the prompt’s language (ISO 639-1, e.g. `en`, `de`). See the Reference for the full list. Prompts whose language is not detected yet are not returned while this filter is applied.
columns	Array of String	No	N/A	Columns to compute, for both `group_mode` values: `prompt`, `topic`, `visibility`, `sov`, `avg_position`, `competitors`, `sentiments`, `locations`, `source_presence`, `intent`, `funnel_stage`, `is_branded`, `organic_overlap`, `lang_code`. When omitted, every metric is computed. See the note below.
cited_source[type]	String	No	N/A	Keep only the prompts whose answers cited one source row from Get project sources in the base period (`date_range[1]` is ignored for it): `url`, `domain`, or `subdomain`. `url` needs `cited_source[url_id]`; `domain` and `subdomain` need `cited_source[domain_id]`. Prompt list only: with `group_mode=topic` the request is rejected with `422`.
cited_source[url_id]	Integer	No	N/A	The `url_id` of the cited URL row. Minimum 1. Required with `cited_source[type]=url`, rejected otherwise.
cited_source[domain_id]	Integer	No	N/A	Minimum 1. Required with `cited_source[type]=domain` or `subdomain`, rejected with `url`. For `subdomain` it is the row’s own `domain_id`; for `domain` it is the `domain_id` the domain row returns.
metrics	Array of String	No	N/A	Facts about the `cited_source` to add to each prompt as extra fields: `citations_count`, `citations_share`, `first_seen`, `last_seen`. Requires `cited_source`, otherwise the request is rejected with `422`.
prompt_ids	Array of Integer	No	N/A	Compute the metrics from the answers of these prompts only; the listed rows are not narrowed. Ignored when `search_query`, `exclude_branded`, `funnel_stages`, `search_intents`, or `lang_codes` is set.
req_num	Integer	No	N/A	Compute the metrics from the answers with this `request_number` only; the listed rows are not narrowed. Ignored when `search_query`, `exclude_branded`, `funnel_stages`, `search_intents`, or `lang_codes` is set.

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. A prompt or topic without a source_presence or organic_overlap value in the period stays last in either direction, also under their _delta variants. citations_count and citations_share sort by the answers that cited the cited_source and require it, otherwise the request is rejected with 422. avg_position and avg_position_delta run inverted: desc puts the best position, or the biggest improvement, first.

Note: with columns, the response keeps the same shape but skips the work behind the columns you do not list: competitors (tops comes back empty), organic_overlap and source_presence (their metrics come back with a null value, unless you sort by that metric or its change). The prompt column and the base metrics (mentions, avg_position, sentiments, visibility, sov) are always computed. An unknown column ID is rejected with 422.

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[].locations	Array	Locations the prompt is currently tracked in, in creation order. Period and `model_types` filters do not narrow it.
items[].locations[].id	String (UUID)	Tracked location ID.
items[].locations[].country_code	String	Country code of the location (e.g. `US`).
items[].locations[].geo_location_id	Integer or null	Geo location ID of the city or region. `null` for country-level tracking.
items[].units	Integer	Number of current locations; equals the length of `locations`.
items[].mentions	Object	Number of the prompt’s answers that mention the primary brand. See MetricValue.
items[].avg_position	Object	Primary brand’s average place among the brands an answer names (1 = first, lower is better), over the answers that mention it; `0` when none does. See MetricValue.
items[].sentiments	Object	Primary brand’s sentiment score, −100–100: (positive − negative mentions) / all its mentions × 100. See MetricValue.
items[].visibility	Object	Primary brand’s visibility score, 0–100: the share of answers that mention it, weighted by its place (first place counts in full, later places less). See MetricValue.
items[].sov	Object	Primary brand’s share of voice, 0–100: answers mentioning it as a percentage of all brands’ answer mentions. 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[].source_presence	Object	Share of the prompt’s answers in the period that cite at least one source page, as a whole percentage. Pooled over every engine and location the filters leave. `values` is `null` when the period holds no answers, `0` when answers arrived but none cited a source. See MetricValue.
items[].search_intent	Array or null	Search intent codes (e.g. `["I"]`). `null` when not applicable.
items[].funnel_stage	Array or null	Funnel stages the prompt belongs to: `awareness`, `consideration`, `decision`, `none` (outside the funnel). `null` when the prompt is not classified yet, and also when it is stored with an empty stage set (the prompt details endpoint returns `["none"]` for it).
items[].lang_code	String or null	ISO 639-1 code of the language the prompt is written in. `null` when the language is not detected yet.
items[].is_branded	Boolean or null	Whether the prompt text names a brand (yours, a tracked competitor, or any other). `null` when the prompt is not classified yet.
items[].citations_count	Integer	Answers of the prompt that cited the `cited_source`. Present only when `metrics[]=citations_count` is requested with a `cited_source`.
items[].citations_share	Float	`citations_count` as a percentage of the prompt’s answers in the period that name one or more brands, one decimal. Present only when `metrics[]=citations_share` is requested with a `cited_source`.
items[].first_seen	String	First answer citing the `cited_source` (`YYYY-MM-DD HH:MM:SS`). Present only when `metrics[]=first_seen` is requested with a `cited_source`.
items[].last_seen	String	Last answer citing the `cited_source` (`YYYY-MM-DD HH:MM:SS`). Present only when `metrics[]=last_seen` is requested with a `cited_source`.
items[].tops	Array	Brands with the best average position in the prompt’s answers, best first (`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, source_presence) 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, organic_overlap, and source_presence 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&cited_source[type]=domain&cited_source[domain_id]=123&metrics[]=citations_count&metrics[]=citations_share&metrics[]=first_seen&metrics[]=last_seen' \

  -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?",

      "locations": [ { "id": "9f8c2b1a-1e2d-4c3b-8a7f-0d1e2c3b4a59", "country_code": "US", "geo_location_id": null } ],

      "units": 1,

      "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 } },

      "source_presence": { "values": [60, 52],   "delta": { "absolute": 8,    "percentage": 15.4 } },

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

      "is_parsed": true,

      "search_intent": ["I"],

      "funnel_stage": ["consideration"],

      "lang_code": "en",

      "is_branded": false,

      "citations_count": 41,

      "citations_share": 68.3,

      "first_seen": "2026-08-04 09:12:00",

      "last_seen": "2026-08-30 17:40:00"

    }

  ]

}

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 the topic’s prompts that the prompt-level filters leave.
items[].branded_prompts_count	Integer	Number of the topic’s prompts whose text names a brand. Subtract it from `prompts_count` to get the non-branded population that `exclude_branded` keeps.
items[].locations	Array	Locations the topic’s current prompts track, each once, in the project’s creation order. Empty for a topic without prompts.
items[].locations[].id	String (UUID)	Tracked location ID.
items[].locations[].country_code	String	Country code of the location (e.g. `US`).
items[].locations[].geo_location_id	Integer or null	Geo location ID of the city or region. `null` for country-level tracking.
items[].mentions	Object	Number of the topic’s answers that mention the primary brand. 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[].source_presence	Object	Share of all answers of the topic’s prompts that cite at least one source page, as a whole percentage, pooled over the same answers as at prompt level. `values` is `null` when the period holds no answers, `0` when none cited a source. See MetricValue.
items[].search_intent	Array or null	Search intent codes present among the topic’s prompts (e.g. `["I"]`). `null` when none of them is classified yet.
items[].funnel_stage	Array or null	Every funnel stage present among the topic’s prompts, each listed once. `null` when none of them is classified yet.
items[].lang_code	Array or null	Languages present among the topic’s prompts, each ISO 639-1 code once, sorted. `null` when none of them has a detected language yet.
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, branded_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,

      "branded_prompts_count": 0,

      "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] },

      "source_presence": { "values": [45, 40],   "delta": { "absolute": 5,   "percentage": 12.5 } },

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

      "search_intent": ["I"],

      "funnel_stage": ["awareness", "consideration"],

      "lang_code": ["en"],

      "locations": [ { "id": "9f8c2b1a-1e2d-4c3b-8a7f-0d1e2c3b4a59", "country_code": "US", "geo_location_id": null } ]

    }

  ]

}

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. Provide prompt_ids to delete individual prompts and/or topic_ids to delete all prompts of the given topics. At least one of the two must be supplied.

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	No	IDs of the prompts to delete.
topic_ids	Array of Integer	No	IDs of topics whose prompts should all be deleted.

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 in the selected locations.

Note:

Omit location_ids to track the prompts in the project’s default location (its oldest location that still tracks an engine).
Each prompt costs one prompt per selected location: 3 prompts over 2 locations charge 6 against your plan’s prompt limit. If they do not fit, the request is rejected with 403 (insufficient_limit) and nothing is created. The prompt’s language and the number of tracked engines do not multiply the charge.
Repeated texts, and texts that already exist in the topic, are not created again, so the response may list fewer IDs than you sent, or be [].

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: at least one text, each non-empty and at most 2000 characters.
location_ids	Array of String (UUID)	No	Project locations to track the prompts in, using location IDs from List project locations. At least one ID; an empty array is rejected. An ID that is not the project’s own, or of a deleted location, is rejected with `422` (`location_invalid`).

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?"

    ],

    "location_ids": [

      "9f8c2b1a-1e2d-4c3b-8a7f-0d1e2c3b4a59",

      "1b2c3d4e-5f60-4718-9a2b-3c4d5e6f7081"

    ]

  }'

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.
search_intent	Array or null	Search intent codes: `I` (informational), `L` (local), `N` (navigational), `C` (commercial), `T` (transactional). `null` when the prompt is not classified yet; an empty array when it carries no intent.
funnel_stage	Array or null	Funnel stages the prompt belongs to: `awareness`, `consideration`, `decision`, `none` (outside the funnel). `null` when the prompt is not classified yet.
lang_code	String or null	ISO 639-1 code of the language the prompt is written in. `null` when the language is not detected yet.
is_branded	Boolean or null	Whether the prompt text names a brand (yours, a tracked competitor, or any other). `null` when the prompt is not classified yet.

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,

  "search_intent": ["L", "C"],

  "funnel_stage": ["consideration"],

  "lang_code": "en",

  "is_branded": false

}

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. You get one result per answer of each location–engine pair the prompt is tracked in; answers of a deleted engine or location, or of a location no longer assigned to the prompt, are excluded.

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	Array of Object	Yes	N/A	1 to 2 entries: 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`). See the Reference for the full list.
country_codes	Array of String	No	N/A	Deprecated — use `location_ids`. Filter by ISO 3166-1 alpha-2 country codes, resolved to the project’s live locations in those countries. It still works for now; migrate to `location_ids` before it is withdrawn. See the Reference for the full list.
location_ids	Array of String (UUID)	No	N/A	Filter by the project’s tracked locations, using location IDs from List project locations. Multiple values combine as OR. An ID of another project or of a deleted location is rejected with `422`. Combined with `country_codes`, only locations matching both are read.
sentiments	Array of String	No	N/A	Filter by sentiment: `positive`, `neutral`, `negative`.
exclude_branded	Boolean	No	N/A	Accepted so the same control can be sent with every request, but not applied here: a branded prompt still returns its answers. The response is the same with and without it.
metrics	Array of String	No	N/A	Extra per-answer fields to add to each item: `sources_count` (distinct pages the answer cited), `cited_domains` (distinct domains of those pages, alphabetically).
sort_field	String	No	`created_at`	Order of the answers: `created_at` (newest first by default), `avg_position` (the primary brand’s position, best first by default; answers without a mention last either way), `sources_count` (most pages cited first by default). Ties break on the newest check.
sort_order	String	No	N/A	Sort direction: `asc` or `desc`. When omitted, the direction depends on `sort_field`: `created_at` and `sources_count` sort descending, `avg_position` sorts the best position first.
search_query	String	No	N/A	Filter results by a search string.
limit	Integer	No	`1000`	Maximum number of items to return. Minimum 0; `0` returns every result and ignores `offset`.
offset	Integer	No	`0`	Number of items to skip from the start of the list. Minimum 0.

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&metrics[]=sources_count&metrics[]=cited_domains' \

  -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_id	Integer	ID of the prompt the result belongs to.
items[].prompt	String	Prompt text.
items[].request_number	Integer	Request number for this prompt run.
items[].avg_position	Float	Primary brand’s place among the brands the answer names (1 = first, lower is better); `0` when the answer does not mention it.
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`, `google_ai_mode`, `google_ai_overview`.
items[].location_id	String (UUID)	Project location the answer was collected under.
items[].sources_count	Integer	Distinct pages the answer cited. Present only when `metrics[]=sources_count` is requested.
items[].cited_domains	Array of String	Distinct domains of the pages the answer cited, alphabetically. Present only when `metrics[]=cited_domains` is requested.
total	Integer	Total number of results available.

Response example

Copy

{

  "items": [

    {

      "id": 101,

      "prompt_id": 1,

      "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",

      "location_id": "9f8c2b1a-1e2d-4c3b-8a7f-0d1e2c3b4a59",

      "sources_count": 7,

      "cited_domains": ["coffeeblog.com", "example.com"]

    },

    {

      "id": 102,

      "prompt_id": 1,

      "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",

      "location_id": "9f8c2b1a-1e2d-4c3b-8a7f-0d1e2c3b4a59",

      "sources_count": 0,

      "cited_domains": []

    }

  ],

  "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	Primary brand’s place among the brands the answer names (1 = first, lower is better); `0` when the answer does not mention it.
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`, `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