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

# Sponsored Content

> Sponsored placements detected in AI responses

Access sponsored content (ads) detected in AI responses, primarily from ChatGPT. Track which advertisers appear, what products they promote, and which prompts trigger these placements.

## List Sponsored Content

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

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

### 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`).
</ParamField>

<ParamField query="advertiser" type="string">
  Filter by advertiser name (case-insensitive partial match)
</ParamField>

<ParamField query="limit" type="number" default="50">
  Maximum number of results 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="createdAt">
  Field to sort by: `createdAt`, `advertiserName`, `productName`, `position`
</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 sponsored placements matching filters</ResponseField>
    <ResponseField name="count" type="number">Number of items 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="sponsored" type="array">
  <Expandable title="Sponsored content object">
    <ResponseField name="id" type="string">Sponsored content record ID</ResponseField>
    <ResponseField name="advertiserName" type="string">Name of the advertiser</ResponseField>
    <ResponseField name="advertiserLogo" type="string">URL of the advertiser's logo</ResponseField>
    <ResponseField name="productName" type="string">Name of the advertised product</ResponseField>
    <ResponseField name="description" type="string">Product description text</ResponseField>
    <ResponseField name="imageUrl" type="string">Product image URL</ResponseField>
    <ResponseField name="position" type="number">Position of the ad within the response (1 = first)</ResponseField>
    <ResponseField name="provider" type="string">AI provider model ID</ResponseField>
    <ResponseField name="competitorRelationship" type="string">Relationship to your brand if advertiser is a known competitor: `SELF`, `DIRECT`, `INDIRECT`, or `null`</ResponseField>
    <ResponseField name="prompt" type="string">Original prompt that triggered this sponsored placement</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601 timestamp</ResponseField>
  </Expandable>
</ResponseField>

### Example Request

```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"
```

### Example Response

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 24,
    "count": 2,
    "limit": 10,
    "offset": 0
  },
  "sponsored": [
    {
      "id": "sp1",
      "advertiserName": "Expedia",
      "advertiserLogo": "https://bzrcdn.openai.com/expedia-logo.png",
      "productName": "Cheap Flights from Chicago, IL",
      "description": "Compare Cheap Flights from Chicago, Illinois. View Deals and Book Now on Expedia.",
      "imageUrl": null,
      "position": 1,
      "provider": "chatgpt-4o",
      "competitorRelationship": "DIRECT",
      "prompt": "What are the best flight deals from Chicago?",
      "createdAt": "2026-04-10T14:30:00Z"
    },
    {
      "id": "sp2",
      "advertiserName": "Nordstrom",
      "advertiserLogo": "https://bzrcdn.openai.com/nordstrom-logo.png",
      "productName": "Spring Collection Sale",
      "description": "Shop the latest spring styles at Nordstrom. Free shipping and returns.",
      "imageUrl": null,
      "position": 1,
      "provider": "chatgpt-4o",
      "competitorRelationship": null,
      "prompt": "Best spring fashion deals 2026",
      "createdAt": "2026-04-09T09:15:00Z"
    }
  ]
}
```

### Error Responses

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