List Prompts

Get paginated prompts with search and filtering options

GET /api/v1/brands/{brandId}/prompts

List Prompts

cURL

curl --request GET \
  --url https://api.example.com/api/v1/brands/{brandId}/prompts \
  --header 'Authorization: <authorization>'

200

{
  "success": true,
  "pagination": {
    "total": 123,
    "count": 123,
    "limit": 123,
    "offset": 123
  },
  "prompts": [
    {
      "id": "<string>",
      "text": "<string>",
      "topic": "<string>",
      "type": "<string>",
      "tags": [
        {}
      ],
      "answersCount": 123,
      "mentionRate": 123,
      "sourceRate": 123,
      "lastGeneratedAt": "<string>",
      "competitors": [
        {}
      ],
      "competitorsCount": 123,
      "competitorMentionsTotal": 123,
      "brandMentioned": true,
      "brandMentionCount": 123,
      "sources": [
        {}
      ],
      "sourcesCount": 123,
      "sourceCitationsTotal": 123,
      "sourceStability": 123,
      "createdAt": "<string>"
    }
  ]
}

Prompts are the questions Qwairy monitors across AI platforms. Each prompt is categorized by funnel stage (TOFU/MOFU/BOFU), tagged for organization, and linked to a topic. Track which prompts generate mentions and source citations for your brand.

See Entities for the complete Prompt object structure, and Topic / Tag for classification objects.

Authorization · string · required

Bearer token. Example: Bearer qw-api-xxx

Path Parameters

brandId · string · required

The unique identifier of the brand

Query Parameters

period · number

Number of days to include. Returns prompts that received at least one answer within the window. If not specified, returns all data.

startDate · string

Start date (ISO 8601, e.g. 2026-03-05). Returns prompts with at least one answer on or after this date.

endDate · string

End date (ISO 8601, e.g. 2026-03-31). Returns prompts with at least one answer on or before this date.

When a date range is provided, both the prompt list and the per-prompt include=details aggregations (answersCount, competitors[].mentions, brandMentionCount, sources[].citations) are scoped to that window. Prompts that ran multiple times still appear if at least one of their runs falls inside the range.

topic · string

Filter by topic ID (keywordId). Supports comma-separated multi-select (e.g., id1,id2).

tag · string

Filter by tag ID. Supports comma-separated multi-select (e.g., id1,id2).

type · string

Filter by prompt type: TOFU, MOFU, BOFU

limit · number · default: "50"

Maximum number of prompts to return (max: 100)

offset · number · default: "0"

Pagination offset

sort · string · default: "lastGeneratedAt"

Field to sort by: lastGeneratedAt, answersCount, text, createdAt

order · string · default: "desc"

Sort order: asc or desc

include · string

Set to details to enrich each prompt with aggregated competitors, sources, brand mentions, and source stability metrics. When omitted, the response includes only the base fields listed below.

Response

success · boolean

Indicates if the request was successful

pagination · object

Show Pagination info

total · number

Total number of prompts matching filters

count · number

Number of prompts in this response

limit · number

Maximum items per page

offset · number

Number of items skipped

prompts · array

Show Prompt object

id · string

Prompt ID

text · string

Prompt text

topic · string

Associated topic name

type · string

Prompt type (TOFU/MOFU/BOFU)

tags · array

List of tag names

answersCount · number

Number of generated answers

mentionRate · number

Brand mention rate (%)

sourceRate · number

Source citation rate (%)

lastGeneratedAt · string

Last generation timestamp (ISO 8601)

Show Additional fields when include=details

competitors · array

List of competitors mentioned across all answers for this prompt. Each object contains name (string), mentions (number), and relationship (SELF, DIRECT, INDIRECT).

competitorsCount · number

Number of unique competitors mentioned

competitorMentionsTotal · number

Total competitor mentions across all answers

brandMentioned · boolean

Whether your brand was mentioned in any answer

brandMentionCount · number

Number of times your brand was mentioned

sources · array

List of source domains cited across all answers for this prompt. Each object contains domain (string), citations (number), and isSelf (boolean).

sourcesCount · number

Number of unique source domains cited

sourceCitationsTotal · number

Total source citations across all answers

sourceStability · number

Percentage of sources present in all answers (0-100). Indicates how consistently sources are cited across different AI responses.

createdAt · string

Prompt creation timestamp (ISO 8601)

Example Request

curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/prompts?type=TOFU&limit=10" \
  -H "Authorization: Bearer qw-api-your-token-here"

Example Response

{
  "success": true,
  "pagination": {
    "total": 156,
    "count": 1,
    "limit": 10,
    "offset": 0
  },
  "prompts": [
    {
      "id": "q1",
      "text": "What are the best products in this category?",
      "topic": "Product Reviews",
      "type": "TOFU",
      "tags": ["reviews", "comparison"],
      "answersCount": 2,
      "mentionRate": 50.0,
      "sourceRate": 25.0,
      "lastGeneratedAt": "2024-12-19T10:00:00.000Z"
    }
  ]
}

Example with include=details

curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/prompts?include=details&limit=10" \
  -H "Authorization: Bearer qw-api-your-token-here"

{
  "success": true,
  "pagination": {
    "total": 156,
    "count": 1,
    "limit": 10,
    "offset": 0
  },
  "prompts": [
    {
      "id": "q1",
      "text": "What are the best products in this category?",
      "topic": "Product Reviews",
      "type": "TOFU",
      "tags": ["reviews", "comparison"],
      "answersCount": 2,
      "mentionRate": 50.0,
      "sourceRate": 25.0,
      "lastGeneratedAt": "2024-12-19T10:00:00.000Z",
      "competitors": [
        { "name": "My Brand", "mentions": 3, "relationship": "SELF" },
        { "name": "Competitor A", "mentions": 8, "relationship": "DIRECT" },
        { "name": "Competitor B", "mentions": 5, "relationship": "DIRECT" }
      ],
      "competitorsCount": 3,
      "competitorMentionsTotal": 16,
      "brandMentioned": true,
      "brandMentionCount": 3,
      "sources": [
        { "domain": "mybrand.com", "citations": 2, "isSelf": true },
        { "domain": "expert-reviews.com", "citations": 4, "isSelf": false },
        { "domain": "industry-news.com", "citations": 3, "isSelf": false }
      ],
      "sourcesCount": 3,
      "sourceCitationsTotal": 9,
      "sourceStability": 33.33,
      "createdAt": "2024-12-01T10:00:00.000Z"
    }
  ]
}