> ## 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 answers

> Retrieve AI-generated responses with filters for provider, brand mentions, and sources.

Returns stored answers for monitored prompts. The list contains a text preview and response-level SELF flags; use [Get Answer](/developers/endpoints/answers/get) for full evidence.

<Note>
  See [Entities](/developers/entities#answer) for the complete Answer object structure, including [CompetitorMention](/developers/entities#competitormention) and [SourceCitation](/developers/entities#sourcecitation) details.
</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. If not specified, returns all data.
</ParamField>

<ParamField query="startDate" type="string">
  Start date in `YYYY-MM-DD`. Provide it with `endDate`; a lone boundary is currently ignored. Choose either `period` or the complete date pair.
</ParamField>

<ParamField query="endDate" type="string">
  End date in `YYYY-MM-DD`. Provide it with `startDate`; a lone boundary is currently ignored. Do not combine the complete date pair with `period`.
</ParamField>

<ParamField query="provider" type="string">
  Filter by AI provider. Supports comma-separated multi-select (e.g., `chatgpt,claude`).
</ParamField>

<ParamField query="topic" type="string">
  Filter by topic ID. 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="hasSelfMention" type="boolean">
  Filter by presence of brand mention: `true` or `false`
</ParamField>

<ParamField query="hasSelfSource" type="boolean">
  Use `true` to require a SELF citation. The current route accepts `false` but does not apply an inverse filter.
</ParamField>

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

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

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

<ParamField query="order" type="string" default="desc">
  Sort order: `asc` or `desc`
</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 answers matching filters</ResponseField>
    <ResponseField name="count" type="number">Number of answers 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="answers" type="array">
  <Expandable title="Answer summary">
    <ResponseField name="id" type="string">Answer ID</ResponseField>
    <ResponseField name="promptId" type="string">Associated prompt ID</ResponseField>
    <ResponseField name="promptText" type="string">Associated prompt text</ResponseField>
    <ResponseField name="provider" type="string">AI provider name</ResponseField>
    <ResponseField name="model" type="string">AI model name</ResponseField>
    <ResponseField name="textPreview" type="string">First 200 characters of the response</ResponseField>
    <ResponseField name="hasSelfMention" type="boolean">Whether brand is mentioned</ResponseField>
    <ResponseField name="selfMentionPosition" type="number">Position in mention list (if mentioned)</ResponseField>
    <ResponseField name="hasSelfSource" type="boolean">Whether brand domain is cited</ResponseField>
    <ResponseField name="competitorsCount" type="number">Number of competitors mentioned</ResponseField>
    <ResponseField name="sourcesCount" type="number">Number of sources cited</ResponseField>
    <ResponseField name="sentiment" type="number | null">SELF mention sentiment on a 0 to 100 scale, or `null`</ResponseField>
    <ResponseField name="createdAt" type="string">Generation timestamp (ISO 8601)</ResponseField>
  </Expandable>
</ResponseField>

## Synthetic request

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/answers?hasSelfMention=true&limit=10" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

## Synthetic response

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 312,
    "count": 1,
    "limit": 10,
    "offset": 0
  },
  "answers": [
    {
      "id": "answer_01",
      "promptId": "prompt_01",
      "promptText": "Which analytics platforms support warehouse exports?",
      "provider": "ChatGPT",
      "model": "GPT-5.4",
      "textPreview": "Acme Analytics and Rival Labs both document warehouse export integrations...",
      "hasSelfMention": true,
      "selfMentionPosition": 3,
      "hasSelfSource": false,
      "competitorsCount": 5,
      "sourcesCount": 3,
      "sentiment": 82,
      "createdAt": "2026-07-19T10:00:00.000Z"
    }
  ]
}
```

## Filtering examples

### Find answers with a SELF mention

```bash theme={null}
GET /api/v1/brands/{brandId}/answers?hasSelfMention=true
```

### Find answers with a SELF citation

```bash theme={null}
GET /api/v1/brands/{brandId}/answers?hasSelfSource=true
```

### Combine filters

```bash theme={null}
# Answers with a SELF mention from the ChatGPT provider
GET /api/v1/brands/{brandId}/answers?provider=openai&hasSelfMention=true
```

The endpoint does not currently support an inverse SELF-citation filter. To find answers that mention the brand without a SELF citation, request `hasSelfMention=true` and filter the returned `hasSelfSource` field in your client.

## Errors

| Status | Meaning |
| - | - |
| `400` | Invalid query parameter |
| `401` | Missing or invalid API token |
| `404` | Brand not found or inaccessible |
| `429` | Rate limit exceeded; honor `Retry-After` |

See [Rate limits](/developers/rate-limits) for retry behavior.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.