> ## 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 contenus sponsorisés

> Listez les emplacements sponsorisés détectés dans les réponses enregistrées.

Renvoie les emplacements sponsorisés conservés à partir des réponses enregistrées. Un enregistrement reflète la réponse capturée à ce moment-là ; il ne confirme ni une campagne active ni une relation avec l’annonceur.

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

```http theme={null}
GET /api/v1/brands/{brandId}/sponsored
```

## 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 un ou plusieurs alias de fournisseurs ou identifiants de modèles, séparés par des virgules.
</ParamField>

<ParamField query="advertiser" type="string">
  Filtre par nom d’annonceur (correspondance partielle, sans tenir compte de la casse)
</ParamField>

<ParamField query="limit" type="number" default="50">
  Nombre maximal de résultats renvoyés (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="createdAt">
  Champ de tri : `createdAt`, `advertiserName`, `productName`, `position`
</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’emplacements sponsorisés correspondant aux filtres</ResponseField>
    <ResponseField name="count" type="number">Nombre d’éléments 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="sponsored" type="array">
  <Expandable title="Objet contenu sponsorisé">
    <ResponseField name="id" type="string">Identifiant de l’enregistrement sponsorisé</ResponseField>
    <ResponseField name="advertiserName" type="string">Nom de l’annonceur</ResponseField>
    <ResponseField name="advertiserLogo" type="string">URL du logo de l’annonceur</ResponseField>
    <ResponseField name="productName" type="string">Nom du produit mis en avant</ResponseField>
    <ResponseField name="description" type="string">Texte de description du produit</ResponseField>
    <ResponseField name="imageUrl" type="string">URL de l’image du produit</ResponseField>
    <ResponseField name="position" type="number">Position de la publicité dans la réponse (1 = première)</ResponseField>
    <ResponseField name="provider" type="string">Identifiant du modèle du fournisseur IA</ResponseField>
    <ResponseField name="competitorRelationship" type="string">Relation avec votre marque si l’annonceur est un concurrent connu : `SELF`, `DIRECT`, `INDIRECT` ou `null`</ResponseField>
    <ResponseField name="prompt" type="string">Prompt associé à l’emplacement enregistré</ResponseField>
    <ResponseField name="createdAt" type="string">Horodatage ISO 8601</ResponseField>
  </Expandable>
</ResponseField>

## Exemple de requête

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

## Exemple de réponse

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 24,
    "count": 2,
    "limit": 10,
    "offset": 0
  },
  "sponsored": [
    {
      "id": "sp1",
      "advertiserName": "Orbit Travel",
      "advertiserLogo": "https://assets.orbit.example/logo.png",
      "productName": "Sample flight offer",
      "description": "Synthetic sponsored placement description.",
      "imageUrl": null,
      "position": 1,
      "provider": "openai-chatgpt-core",
      "competitorRelationship": "DIRECT",
      "prompt": "What are the best flight deals from Chicago?",
      "createdAt": "2026-04-10T14:30:00Z"
    },
    {
      "id": "sp2",
      "advertiserName": "Northstar Retail",
      "advertiserLogo": "https://assets.northstar.example/logo.png",
      "productName": "Sample seasonal offer",
      "description": "Synthetic sponsored placement description.",
      "imageUrl": null,
      "position": 1,
      "provider": "google-ai-mode-core",
      "competitorRelationship": null,
      "prompt": "Best spring fashion deals 2026",
      "createdAt": "2026-04-09T09:15:00Z"
    }
  ]
}
```

## Erreurs

| Statut | Code | Description |
| - | - | - |
| 400 | `INVALID_PARAMETER` | Valeur de filtre, de pagination ou de tri invalide |
| 401 | erreur de passerelle | Échec de l’authentification |
| 404 | `BRAND_NOT_FOUND` | Marque inexistante ou inaccessible |
| 429 | erreur de passerelle | Limite de débit dépassée ; respectez `Retry-After` |


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