> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwairy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# List Prompts

> Get paginated prompts with search and filtering options

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.

<Note>
  See [Entities](/developers/entities#prompt) for the complete Prompt object structure, and [Topic](/developers/entities#topic) / [Tag](/developers/entities#tag) for classification objects.
</Note>

<ParamField header="Authorization" type="string" required>
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

### Path Parameters

<ParamField path="brandId" type="string" required>
  The unique identifier of the brand
</ParamField>

### Query Parameters

<ParamField query="period" type="number">
  Number of days to include. Returns prompts that received at least one answer within the window. If not specified, returns all data.
</ParamField>

<ParamField query="startDate" type="string">
  Start date (ISO 8601, e.g. `2026-03-05`). Returns prompts with at least one answer on or after this date.
</ParamField>

<ParamField query="endDate" type="string">
  End date (ISO 8601, e.g. `2026-03-31`). Returns prompts with at least one answer on or before this date.
</ParamField>

<Note>
  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.
</Note>

<ParamField query="topic" type="string">
  Filter by topic ID (keywordId). Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField query="tag" type="string">
  Filter by tag ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField query="type" type="string">
  Filter by prompt type: `TOFU`, `MOFU`, `BOFU`
</ParamField>

<ParamField query="limit" type="number" default="50">
  Maximum number of prompts to return (max: 100)
</ParamField>

<ParamField query="offset" type="number" default="0">
  Pagination offset
</ParamField>

<ParamField query="sort" type="string" default="lastGeneratedAt">
  Field to sort by: `lastGeneratedAt`, `answersCount`, `text`, `createdAt`
</ParamField>

<ParamField query="order" type="string" default="desc">
  Sort order: `asc` or `desc`
</ParamField>

<ParamField query="include" type="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.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination info">
    <ResponseField name="total" type="number">Total number of prompts matching filters</ResponseField>
    <ResponseField name="count" type="number">Number of prompts in this response</ResponseField>
    <ResponseField name="limit" type="number">Maximum items per page</ResponseField>
    <ResponseField name="offset" type="number">Number of items skipped</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="prompts" type="array">
  <Expandable title="Prompt object">
    <ResponseField name="id" type="string">Prompt ID</ResponseField>
    <ResponseField name="text" type="string">Prompt text</ResponseField>
    <ResponseField name="topic" type="string">Associated topic name</ResponseField>
    <ResponseField name="type" type="string">Prompt type (TOFU/MOFU/BOFU)</ResponseField>
    <ResponseField name="tags" type="array">List of tag names</ResponseField>
    <ResponseField name="answersCount" type="number">Number of generated answers</ResponseField>
    <ResponseField name="mentionRate" type="number">Brand mention rate (%)</ResponseField>
    <ResponseField name="sourceRate" type="number">Source citation rate (%)</ResponseField>
    <ResponseField name="lastGeneratedAt" type="string">Last generation timestamp (ISO 8601)</ResponseField>
  </Expandable>

  <Expandable title="Additional fields when include=details">
    <ResponseField name="competitors" type="array">
      List of competitors mentioned across all answers for this prompt.
      Each object contains `name` (string), `mentions` (number), and `relationship` (`SELF`, `DIRECT`, `INDIRECT`).
    </ResponseField>

    <ResponseField name="competitorsCount" type="number">Number of unique competitors mentioned</ResponseField>
    <ResponseField name="competitorMentionsTotal" type="number">Total competitor mentions across all answers</ResponseField>
    <ResponseField name="brandMentioned" type="boolean">Whether your brand was mentioned in any answer</ResponseField>
    <ResponseField name="brandMentionCount" type="number">Number of times your brand was mentioned</ResponseField>

    <ResponseField name="sources" type="array">
      List of source domains cited across all answers for this prompt.
      Each object contains `domain` (string), `citations` (number), and `isSelf` (boolean).
    </ResponseField>

    <ResponseField name="sourcesCount" type="number">Number of unique source domains cited</ResponseField>
    <ResponseField name="sourceCitationsTotal" type="number">Total source citations across all answers</ResponseField>
    <ResponseField name="sourceStability" type="number">Percentage of sources present in all answers (0-100). Indicates how consistently sources are cited across different AI responses.</ResponseField>
    <ResponseField name="createdAt" type="string">Prompt creation timestamp (ISO 8601)</ResponseField>
  </Expandable>
</ResponseField>

### Example Request

```bash theme={null}
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

```json theme={null}
{
  "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`

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

```json theme={null}
{
  "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"
    }
  ]
}
```