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

# Entities

> Data models and object structures returned by the API

This page documents all the data entities returned by the Qwairy API. Understanding these structures will help you parse and use the data effectively.

## Pagination

All list endpoints return a consistent pagination structure:

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 156,
    "count": 10,
    "limit": 10,
    "offset": 0
  },
  "data": [ ... ]
}
```

<ResponseField name="pagination" type="object">
  <Expandable title="Pagination object">
    <ResponseField name="total" type="number">
      Total number of items matching the query (across all pages)
    </ResponseField>

    <ResponseField name="count" type="number">
      Number of items returned in this response
    </ResponseField>

    <ResponseField name="limit" type="number">
      Maximum items per page (as requested or default)
    </ResponseField>

    <ResponseField name="offset" type="number">
      Number of items skipped (for pagination)
    </ResponseField>
  </Expandable>
</ResponseField>

### Pagination Example

To fetch page 2 with 20 items per page:

```bash theme={null}
GET /api/v1/brands/{brandId}/prompts?limit=20&offset=20
```

Response:

```json theme={null}
{
  "success": true,
  "pagination": {
    "total": 156,
    "count": 20,
    "limit": 20,
    "offset": 20
  },
  "prompts": [ ... ]
}
```

***

## Brand

A brand represents a company or product you're monitoring across AI platforms.

<Card title="Related Endpoints" icon="link" href="/api-reference/endpoints/brands/list">
  List Brands, Get Brand Details
</Card>

```json theme={null}
{
  "id": "cm1234567890abcdef",
  "name": "My Brand",
  "domain": "mybrand.com",
  "description": "Leading provider of innovative solutions",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "stats": {
    "promptsCount": 156,
    "answersCount": 312,
    "competitorsCount": 8
  }
}
```

<ResponseField name="id" type="string">
  Unique brand identifier (UUID format)
</ResponseField>

<ResponseField name="name" type="string">
  Brand display name
</ResponseField>

<ResponseField name="domain" type="string">
  Primary domain associated with the brand
</ResponseField>

<ResponseField name="description" type="string">
  Optional brand description (can be null)
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of brand creation
</ResponseField>

<ResponseField name="stats" type="object">
  <Expandable title="Brand statistics">
    <ResponseField name="promptsCount" type="number">
      Total prompts tracked for this brand
    </ResponseField>

    <ResponseField name="answersCount" type="number">
      Total AI responses analyzed
    </ResponseField>

    <ResponseField name="competitorsCount" type="number">
      Number of competitors (SELF + DIRECT)
    </ResponseField>
  </Expandable>
</ResponseField>

***

## Competitor

A competitor is a brand or domain that appears in AI-generated responses. Competitors are categorized by their relationship to your brand.

<Card title="Related Endpoints" icon="link" href="/api-reference/endpoints/competitors/list">
  List Competitors, Get Competitor Details, Competitor Evolution
</Card>

```json theme={null}
{
  "id": "cmp_abc123",
  "name": "Competitor Name",
  "domain": "competitor.com",
  "relationship": "DIRECT",
  "totalMentions": 111,
  "shareOfVoice": 8.73,
  "avgPosition": 2.3,
  "avgSentiment": 75.2
}
```

<ResponseField name="id" type="string">
  Unique competitor identifier
</ResponseField>

<ResponseField name="name" type="string">
  Competitor display name
</ResponseField>

<ResponseField name="domain" type="string">
  Competitor's primary domain
</ResponseField>

<ResponseField name="relationship" type="string">
  Relationship type:

  * `SELF`: Your own brand
  * `DIRECT`: Direct competitor (used in Share of Voice calculation)
  * `INDIRECT`: Indirect competitor (mentioned by AI but not a direct rival)

  **Note:** The list and detail endpoints only return `SELF` and `DIRECT` competitors by default. However, answer details may include mentions with all three relationship types. Only `SELF` and `DIRECT` are used for Share of Voice calculations.
</ResponseField>

<ResponseField name="totalMentions" type="number">
  Total number of times mentioned in AI responses
</ResponseField>

<ResponseField name="shareOfVoice" type="number">
  Share of Voice (0-100). This entity's share of all brand mentions in AI responses: its mentions divided by the total of all SELF and DIRECT mentions. INDIRECT mentions are excluded.
</ResponseField>

<ResponseField name="avgPosition" type="number">
  Average position when mentioned in lists (1 = first, lower is better)
</ResponseField>

<ResponseField name="avgSentiment" type="number">
  Average sentiment score (0-100, higher is more positive)
</ResponseField>

***

## Source

A source is a domain cited by AI platforms when generating responses. Track which websites influence AI answers in your industry.

<Card title="Related Endpoints" icon="link" href="/api-reference/endpoints/source-domains/list">
  Source Domains, Source URLs, Source Evolution
</Card>

```json theme={null}
{
  "id": "src_xyz789",
  "domain": "industry-news.com",
  "type": "MEDIA",
  "isSelf": false,
  "totalMentions": 102,
  "rate": 5.10,
  "avgPosition": 3.2
}
```

<ResponseField name="id" type="string">
  Unique source identifier
</ResponseField>

<ResponseField name="domain" type="string">
  Source domain name
</ResponseField>

<ResponseField name="type" type="string">
  Source category:

  * `INSTITUTIONAL`: Official/government sites
  * `COMMERCIAL`: E-commerce, business sites
  * `MEDIA`: News, magazines, publications
  * `BLOG`: Personal or company blogs
  * `SOCIAL`: Social media platforms
  * `FORUM`: Discussion forums, Q\&A sites
  * `EDUCATIONAL`: Universities, courses
  * `OTHER`: Uncategorized
</ResponseField>

<ResponseField name="isSelf" type="boolean">
  Whether this source belongs to your brand
</ResponseField>

<ResponseField name="totalMentions" type="number">
  Total citations in AI responses
</ResponseField>

<ResponseField name="rate" type="number">
  **Share of Citations** - percentage of all AI citations from this source (0-100). Example: `rate: 5.10` means 5.10% of all citations reference this domain.
</ResponseField>

<ResponseField name="avgPosition" type="number">
  Average position in source lists (1 = first)
</ResponseField>

***

## Prompt

A prompt is a question or query monitored across AI platforms. Each prompt is categorized by funnel stage and can have tags for organization.

<Card title="Related Endpoints" icon="link" href="/api-reference/endpoints/prompts/list">
  List Prompts, Get Prompt Details, Prompt Answers
</Card>

```json theme={null}
{
  "id": "q_abc123",
  "text": "What are the best products in this category?",
  "topic": "Product Reviews",
  "type": "TOFU",
  "tags": ["reviews", "comparison"],
  "answersCount": 2,
  "mentionRate": 50.0,
  "sourceRate": 25.0,
  "lastGeneratedAt": "2024-12-19T10:00:00.000Z"
}
```

<ResponseField name="id" type="string">
  Unique prompt identifier
</ResponseField>

<ResponseField name="text" type="string">
  The prompt/question text
</ResponseField>

<ResponseField name="topic" type="string">
  Associated topic/keyword name (can be null)
</ResponseField>

<ResponseField name="type" type="string">
  Marketing funnel stage:

  * `TOFU`: Top of Funnel (awareness)
  * `MOFU`: Middle of Funnel (consideration)
  * `BOFU`: Bottom of Funnel (decision)
</ResponseField>

<ResponseField name="tags" type="array">
  List of tag names for organization
</ResponseField>

<ResponseField name="answersCount" type="number">
  Number of AI responses generated for this prompt
</ResponseField>

<ResponseField name="mentionRate" type="number">
  Percentage of answers mentioning your brand (0-100)
</ResponseField>

<ResponseField name="sourceRate" type="number">
  Percentage of answers citing your domain (0-100)
</ResponseField>

<ResponseField name="lastGeneratedAt" type="string">
  ISO 8601 timestamp of last answer generation
</ResponseField>

***

## Answer

An answer is an AI-generated response to a prompt. Contains the full text, detected brand mentions, and cited sources.

<Card title="Related Endpoints" icon="link" href="/api-reference/endpoints/answers/list">
  List Answers, Get Answer Details
</Card>

```json theme={null}
{
  "id": "ans_123abc",
  "promptId": "q_abc123",
  "promptText": "What are the best products?",
  "provider": "ChatGPT",
  "model": "GPT-4o",
  "text": "Based on recent reviews...",
  "hasSelfMention": true,
  "selfMentionPosition": 3,
  "hasSelfSource": false,
  "competitorsCount": 5,
  "sourcesCount": 3,
  "sentiment": 82,
  "createdAt": "2024-12-19T10:00:00.000Z"
}
```

<ResponseField name="id" type="string">
  Unique answer identifier
</ResponseField>

<ResponseField name="promptId" type="string">
  ID of the associated prompt
</ResponseField>

<ResponseField name="promptText" type="string">
  Text of the associated prompt
</ResponseField>

<ResponseField name="provider" type="string">
  AI provider name (ChatGPT, Perplexity, Claude, etc.)
</ResponseField>

<ResponseField name="model" type="string">
  Specific AI model used (GPT-4o, Sonar Large, etc.)
</ResponseField>

<ResponseField name="text" type="string">
  Full response text (or preview in list endpoints)
</ResponseField>

<ResponseField name="hasSelfMention" type="boolean">
  Whether your brand is mentioned
</ResponseField>

<ResponseField name="selfMentionPosition" type="number">
  Position in competitor list when mentioned (null if not mentioned)
</ResponseField>

<ResponseField name="hasSelfSource" type="boolean">
  Whether your domain is cited as a source
</ResponseField>

<ResponseField name="competitorsCount" type="number">
  Number of competitors mentioned in this answer
</ResponseField>

<ResponseField name="sourcesCount" type="number">
  Number of sources cited in this answer
</ResponseField>

<ResponseField name="sentiment" type="number">
  Sentiment score for your brand mention (0-100, null if not mentioned)
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of answer generation
</ResponseField>

***

## CompetitorMention

Detailed information about a competitor mention within an answer (returned in answer details).

```json theme={null}
{
  "name": "My Brand",
  "position": 3,
  "relationship": "SELF",
  "sentiment": 85
}
```

<ResponseField name="name" type="string">
  Competitor name as mentioned
</ResponseField>

<ResponseField name="position" type="number">
  Position in the response (1 = mentioned first)
</ResponseField>

<ResponseField name="relationship" type="string">
  `SELF`, `DIRECT`, or `INDIRECT`. Answer details return mentions for **all** relationship types. If you're computing Share of Voice, filter to only `SELF` and `DIRECT` mentions.
</ResponseField>

<ResponseField name="sentiment" type="number">
  Sentiment score for this mention (0-100)
</ResponseField>

***

## SourceCitation

Detailed information about a source citation within an answer (returned in answer details).

```json theme={null}
{
  "url": "https://industry-news.com/article",
  "domain": "industry-news.com",
  "position": 1,
  "isSelf": false
}
```

<ResponseField name="url" type="string">
  Full URL cited (can be null)
</ResponseField>

<ResponseField name="domain" type="string">
  Domain name of the source
</ResponseField>

<ResponseField name="position" type="number">
  Position in source list (1 = cited first)
</ResponseField>

<ResponseField name="isSelf" type="boolean">
  Whether this is your own domain
</ResponseField>

***

## Topic

A topic (also called keyword) groups related prompts together.

```json theme={null}
{
  "id": "topic_abc123",
  "name": "Product Reviews"
}
```

<ResponseField name="id" type="string">
  Unique topic identifier
</ResponseField>

<ResponseField name="name" type="string">
  Topic display name
</ResponseField>

***

## Tag

Tags allow custom categorization of prompts.

```json theme={null}
{
  "id": "tag_xyz789",
  "name": "comparison"
}
```

<ResponseField name="id" type="string">
  Unique tag identifier
</ResponseField>

<ResponseField name="name" type="string">
  Tag display name
</ResponseField>

***

## Evolution Data Point

Used in evolution endpoints to track metrics over time.

```json theme={null}
{
  "date": "2024-12-01",
  "mentions": 5,
  "shareOfVoice": 7.2,
  "avgPosition": 2.3,
  "avgSentiment": 76.5
}
```

<ResponseField name="date" type="string">
  Date in YYYY-MM-DD format
</ResponseField>

<ResponseField name="mentions" type="number">
  Number of mentions on this date
</ResponseField>

<ResponseField name="shareOfVoice" type="number">
  Share of voice percentage on this date
</ResponseField>

<ResponseField name="avgPosition" type="number">
  Average position on this date
</ResponseField>

<ResponseField name="avgSentiment" type="number">
  Average sentiment on this date (competitors only)
</ResponseField>