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

# Lister les URL sources

> Suivez les citations page par page.

Liste les URL citées avec leur nombre d’occurrences, leur position moyenne, leur taxonomie et leurs indicateurs de relation pour le périmètre de réponses sélectionné.

<ParamField header="Authorization" type="string" required>
  Jeton bearer. Exemple : `Bearer qw-api-xxx`
</ParamField>

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

## Paramètres de chemin

<ParamField path="brandId" type="string" required>
  L’identifiant unique de la marque
</ParamField>

## Paramètres de requête

<ParamField query="period" type="number">
  Nombre de jours à inclure. Sans valeur, toutes les données sont renvoyées.
</ParamField>

<ParamField query="startDate" type="string">
  Date de début au format `YYYY-MM-DD`. Fournissez-la avec `endDate` ; une borne seule est actuellement ignorée. Choisissez soit `period`, soit la paire de dates complète.
</ParamField>

<ParamField query="endDate" type="string">
  Date de fin au format `YYYY-MM-DD`. Fournissez-la avec `startDate` ; une borne seule est actuellement ignorée. Ne combinez pas la paire de dates complète avec `period`.
</ParamField>

<ParamField query="provider" type="string">
  Filtre par fournisseur IA. Accepte plusieurs valeurs séparées par des virgules (par exemple `chatgpt,claude`).
</ParamField>

<ParamField query="domain" type="string">
  Filtre sur un domaine précis
</ParamField>

<ParamField query="isSelf" type="string">
  Filtre sur vos propres domaines : `true` ou `false`
</ParamField>

<ParamField query="isCompetitor" type="string">
  Filtre sur les domaines concurrents : `true` ou `false`
</ParamField>

<ParamField query="limit" type="number" default="50">
  Nombre maximal d’URL renvoyées (maximum : 100)
</ParamField>

<ParamField query="offset" type="number" default="0">
  Nombre de résultats à ignorer pour la pagination
</ParamField>

<ParamField query="sort" type="string" default="mentions">
  Champ de tri : `mentions`, `position`, `shareOfVoice`, `url`
</ParamField>

<ParamField query="order" type="string" default="desc">
  Ordre de tri : `asc` ou `desc`
</ParamField>

## Réponse

<ResponseField name="success" type="boolean">
  Indique si la requête a réussi
</ResponseField>

<ResponseField name="pagination" type="object">
  <Expandable title="Informations de pagination">
    <ResponseField name="total" type="number">Nombre total d’URL correspondant aux filtres</ResponseField>
    <ResponseField name="count" type="number">Nombre d’URL dans cette réponse</ResponseField>
    <ResponseField name="limit" type="number">Nombre maximal d’éléments par page</ResponseField>
    <ResponseField name="offset" type="number">Nombre d’éléments ignorés</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="sourceUrls" type="array">
  <Expandable title="Objet URL source">
    <ResponseField name="url" type="string">URL complète de la page citée</ResponseField>
    <ResponseField name="title" type="string">Titre de la page (s’il est disponible)</ResponseField>
    <ResponseField name="domain" type="string">Nom de domaine</ResponseField>
    <ResponseField name="isSelf" type="boolean">Indique s’il s’agit de votre domaine</ResponseField>
    <ResponseField name="isCompetitor" type="boolean">Indique s’il s’agit du domaine d’un concurrent direct</ResponseField>
    <ResponseField name="competitors" type="array">Noms des concurrents directs associés à cette URL</ResponseField>
    <ResponseField name="totalMentions" type="number">Nombre total de citations</ResponseField>
    <ResponseField name="avgPosition" type="number">Position moyenne dans les listes de sources</ResponseField>
    <ResponseField name="shareOfVoice" type="number">Part de l’ensemble des citations (0 à 100)</ResponseField>
    <ResponseField name="topics" type="array">Objets Topic associés, avec `id` et `text`</ResponseField>
    <ResponseField name="tags" type="array">Objets Tag associés, avec `id` et `name`</ResponseField>
  </Expandable>
</ResponseField>

## Exemple de requête

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

## Exemple de réponse

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 156,
    "count": 2,
    "limit": 10,
    "offset": 0
  },
  "sourceUrls": [
    {
      "url": "https://acme.example/guides/warehouse-exports",
      "title": "Warehouse export guide",
      "domain": "acme.example",
      "isSelf": true,
      "isCompetitor": false,
      "competitors": [],
      "totalMentions": 45,
      "avgPosition": 2.1,
      "shareOfVoice": 3.5,
      "topics": [{ "id": "topic_01", "text": "Data exports" }],
      "tags": [{ "id": "tag_01", "name": "integrations" }]
    },
    {
      "url": "https://rival.example/docs/export-review",
      "title": "Export integration overview",
      "domain": "rival.example",
      "isSelf": false,
      "isCompetitor": true,
      "competitors": ["Rival Labs"],
      "totalMentions": 32,
      "avgPosition": 3.4,
      "shareOfVoice": 2.1,
      "topics": [{ "id": "topic_01", "text": "Data exports" }],
      "tags": []
    }
  ]
}
```

## Erreurs

| Statut | Code | Description |
| - | - | - |
| 401 | erreur de passerelle | Jeton d’API manquant ou invalide |
| 404 | `BRAND_NOT_FOUND` | Marque inexistante ou inaccessible |
| 429 | erreur de passerelle | Limite de débit dépassée ; respectez `Retry-After` |

`shareOfVoice` correspond aux occurrences de citation de l’URL divisées par toutes les occurrences de citation du périmètre sélectionné. Consultez [Limites de débit](/fr/developers/rate-limits) pour la gestion des nouvelles tentatives.


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