Prompts
List prompts
List a brand's prompts, oldest first, filtered by tracking state, category or theme, with volume and difficulty.
HTTP
GET https://api.ranqo.ai/v1/brands/{brand_id}/promptsThe brand's prompts, oldest first.
Path parameters
| Name | Type | Description |
|---|---|---|
brand_id | string | The brand id, from GET /v1/brands. |
Query parameters
Every parameter is optional. A parameter the endpoint does not take is refused with unknown_parameter.
| Name | Type | Default | Description |
|---|---|---|---|
limit | integer | 50 | Items per page, 1 to 100. |
cursor | string | The next_cursor of the previous page. | |
status | string | Only prompts in this state. One of tracked, paused, never_run. | |
category | string | Only prompts in this category. One of discovery, problem_solution, use_case, expert, comparison, brand_research. | |
theme_id | string | Only prompts in this theme; none for prompts with none. |
Response
The response body, as JSON.
| Field | Type | Description |
|---|---|---|
data | array of objects | |
data[].id | string | |
data[].text | string | |
data[].category | string | One of discovery, problem_solution, use_case, expert, comparison, brand_research. |
data[].status | string | tracked: asked on every run. paused: tracked before, not asked now, its answers kept. never_run: not tracked, and never switched on since tracking dates began to be recorded (March 2026), so a prompt tracked only before then and paused since also reads never_run, as on the dashboard. One of tracked, paused, never_run. |
data[].theme | object or null | |
data[].theme.id | string | |
data[].theme.name | string | |
data[].location | string or null | The market the prompt is asked from, as stored. |
data[].is_branded | boolean | Whether the prompt was recorded as naming the brand when it was generated or added; a prompt added by hand is recorded as not. The text is not re-checked. |
data[].volume | integer or null | Estimated search volume, 1-5. |
data[].difficulty | integer or null | How crowded its answers are with competitors, 0-5: measured once a run asks it, estimated before. |
data[].created_at | string | RFC 3339 timestamp in UTC. |
data[].activated_at | string or null | RFC 3339 timestamp in UTC. When it was first tracked. Null for a prompt never tracked, and for one first tracked before March 2026, when this date began to be recorded. |
has_more | boolean | Whether another page follows. |
next_cursor | string or null | Pass as cursor for the next page; null on the last page. |
Response headers
| Header | Description |
|---|---|
X-Request-Id | The request id; quote it to support. |
RateLimit | Requests left in this window and seconds until it resets. |
RateLimit-Policy | The key's limit per window. |
Example request
curl
curl "https://api.ranqo.ai/v1/brands/BRAND_ID/prompts" \
-H "Authorization: Bearer $RANQO_API_KEY"Errors
Errors are problem details (application/problem+json) with a stable code. See Errors for each one.