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
• download the raw, unmodified LLM response for a result

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

Query parameters

Request example

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'

Response parameters

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

group_mode=prompt

group_mode=topic

Response example

group_mode=prompt

{
  "items": [
    {
      "id": 1,
      "topic_id": 10,
      "prompt": "What is artificial intelligence?",
      "mentions": 45,
      "avg_position": 2.3,
      "sentiments": 0.75,
      "visibility": 1200,
      "sov": 15,
      "tops": [
        { "brand_id": 1, "brand_name": "Google" }
      ],
      "is_parsed": true
    }
  ],
  "total": 127
}

group_mode=topic

{
  "items": [
    {
      "id": 10,
      "title": "Ground Coffee",
      "prompts_count": 5,
      "mentions": 120,
      "avg_position": 2.1,
      "sentiments": 0.68,
      "visibility": 3400,
      "sov": 18,
      "tops": [
        { "brand_id": 1, "brand_name": "Lavazza" }
      ]
    }
  ],
  "total": 5
}

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

Request body

Request example

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

Request body

Request example

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.

Response example

[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

Request body

Request example

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

Request example

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.

Response example

{
  "id": 1,
  "text": "What are the best ground coffee brands for a rich and smooth flavor?",
  "topic_id": 10,
  "created_at": "2023-12-15 10:30:00",
  "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

Query parameters

Request example

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.

Response example

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

Request example

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.

Response example

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

Download raw LLM response dump

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

Returns the raw, unmodified LLM response for a result, exactly as the provider returned it. Use it to compare the original response against the parsed result details.

Note:

• This endpoint returns raw text/html, not JSON. The body is the exact response from the LLM with no modifications.

Request parameters

Path parameters

Request example

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

Response parameters

If successful, the server returns the raw LLM response as text/html. The body is a plain string, not a JSON object.

Response example

<p>Based on extensive research and customer reviews, some of the best ground coffee brands for a rich and smooth flavor include:</p>
<ul>
  <li><strong>Lavazza</strong>: known for its Italian roasting expertise and premium blends.</li>
  <li><strong>Illy</strong>: a smooth, balanced medium roast.</li>
</ul>