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

# Social Signals

> Social platform citations from AI responses

Track citations from social platforms (Reddit, YouTube, Twitter, forums) in AI responses. Understand which social content AI platforms reference when answering questions about your industry.

## List Social Insights

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

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

### 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="platform" type="string">
  Filter by platform: `reddit`, `youtube`, `twitter`, `facebook`, `linkedin`, `other`
</ParamField>

<ParamField query="limit" type="number" default="50">
  Maximum number of citations 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`, `position`, `upvotes`, `comments`, `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 citations matching filters</ResponseField>
    <ResponseField name="count" type="number">Number of citations 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="social" type="array">
  <Expandable title="Social citation object">
    <ResponseField name="id" type="string">Social insight ID</ResponseField>
    <ResponseField name="platform" type="string">Platform name (reddit, youtube, twitter, etc.)</ResponseField>
    <ResponseField name="communityId" type="string">Community identifier (subreddit, channel, etc.)</ResponseField>
    <ResponseField name="communityName" type="string">Community display name</ResponseField>
    <ResponseField name="url" type="string">Full URL of the cited content</ResponseField>
    <ResponseField name="title" type="string">Content title (if available)</ResponseField>
    <ResponseField name="domain" type="string">Domain name</ResponseField>
    <ResponseField name="position" type="number">Position in source list</ResponseField>
    <ResponseField name="upvotes" type="number">Upvotes/likes (Reddit, when available)</ResponseField>
    <ResponseField name="commentCount" type="number">Comment count (when available)</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/social?platform=reddit&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
  },
  "social": [
    {
      "id": "soc1",
      "platform": "reddit",
      "communityId": "SaaS",
      "communityName": "r/SaaS",
      "url": "https://reddit.com/r/SaaS/comments/abc123/best_crm_tools",
      "title": "Best CRM tools for startups in 2024?",
      "domain": "reddit.com",
      "position": 2,
      "upvotes": 245,
      "commentCount": 89,
      "createdAt": "2024-12-15T10:30:00Z"
    },
    {
      "id": "soc2",
      "platform": "youtube",
      "communityId": "TechReviewer",
      "communityName": "TechReviewer",
      "url": "https://youtube.com/@TechReviewer/crm-comparison",
      "title": "CRM Software Comparison 2024",
      "domain": "youtube.com",
      "position": 3,
      "upvotes": 0,
      "commentCount": 0,
      "createdAt": "2024-12-14T15:45:00Z"
    }
  ]
}
```

<Note>
  Social signals like upvotes and comments are only available for platforms that expose this data (primarily Reddit). Other platforms may show 0 for these fields.
</Note>

### Error Responses

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