> ## 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 Source URLs

> Track individual page citations

Get granular URL-level citation data. While the Sources endpoint shows domain-level aggregates, this endpoint provides page-by-page citation details.

## List Source URLs

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

```http theme={null}
GET /api/v1/brands/{brandId}/source-urls
```

### 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 (ISO 8601 format)
</ParamField>

<ParamField query="endDate" type="string">
  End date (ISO 8601 format)
</ParamField>

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

<ParamField query="domain" type="string">
  Filter by specific domain
</ParamField>

<ParamField query="isSelf" type="string">
  Filter by self domains: `true` or `false`
</ParamField>

<ParamField query="isCompetitor" type="string">
  Filter by competitor domains: `true` or `false`
</ParamField>

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

<ParamField query="offset" type="number" default="0">
  Number of results to skip for pagination
</ParamField>

<ParamField query="sort" type="string" default="mentions">
  Field to sort by: `mentions`, `position`, `shareOfVoice`, `url`
</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 URLs matching filters</ResponseField>
    <ResponseField name="count" type="number">Number of URLs 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="sourceUrls" type="array">
  <Expandable title="Source URL object">
    <ResponseField name="url" type="string">Full URL of the cited page</ResponseField>
    <ResponseField name="title" type="string">Page title (if available)</ResponseField>
    <ResponseField name="domain" type="string">Domain name</ResponseField>
    <ResponseField name="isSelf" type="boolean">Whether this is your domain</ResponseField>
    <ResponseField name="isCompetitor" type="boolean">Whether this is a direct competitor's domain</ResponseField>
    <ResponseField name="competitors" type="array">Names of direct competitors associated with this URL</ResponseField>
    <ResponseField name="totalMentions" type="number">Total citation count</ResponseField>
    <ResponseField name="avgPosition" type="number">Average position in source lists</ResponseField>
    <ResponseField name="shareOfVoice" type="number">Share of all citations (0-100)</ResponseField>
  </Expandable>
</ResponseField>

### Example Request

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

### Example Response

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 156,
    "count": 2,
    "limit": 10,
    "offset": 0
  },
  "sourceUrls": [
    {
      "url": "https://mybrand.com/blog/best-practices",
      "title": "Best Practices Guide - MyBrand",
      "domain": "mybrand.com",
      "isSelf": true,
      "isCompetitor": false,
      "competitors": [],
      "totalMentions": 45,
      "avgPosition": 2.1,
      "shareOfVoice": 3.5
    },
    {
      "url": "https://competitor.com/blog/review",
      "title": "Product Review - Competitor",
      "domain": "competitor.com",
      "isSelf": false,
      "isCompetitor": true,
      "competitors": ["Competitor Inc"],
      "totalMentions": 32,
      "avgPosition": 3.4,
      "shareOfVoice": 2.1
    }
  ]
}
```

### Error Responses

| Status | Code              | Description                           |
| ------ | ----------------- | ------------------------------------- |
| 401    | `INVALID_TOKEN`   | Authentication failed                 |
| 404    | `BRAND_NOT_FOUND` | Brand doesn't exist or not accessible |