Entities - Qwairy Documentation

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:

{
  "success": true,
  "pagination": {
    "total": 156,
    "count": 10,
    "limit": 10,
    "offset": 0
  },
  "data": [ ... ]
}

pagination

object

Show Pagination object

Pagination Example

To fetch page 2 with 20 items per page:

GET /api/v1/brands/{brandId}/prompts?limit=20&offset=20

Response:

{
  "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.

Related Endpoints

List Brands, Get Brand Details

{
  "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
  }
}

string

Unique brand identifier (UUID format)

name

string

Brand display name

domain

string

Primary domain associated with the brand

description

string

Optional brand description (can be null)

createdAt

string

ISO 8601 timestamp of brand creation

stats

object

Show Brand statistics

promptsCount

number

Total prompts tracked for this brand

answersCount

number

Total AI responses analyzed

competitorsCount

number

Number of competitors (SELF + DIRECT)

Competitor

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

Related Endpoints

List Competitors, Get Competitor Details, Competitor Evolution

{
  "id": "cmp_abc123",
  "name": "Competitor Name",
  "domain": "competitor.com",
  "relationship": "DIRECT",
  "totalMentions": 111,
  "shareOfVoice": 8.73,
  "avgPosition": 2.3,
  "avgSentiment": 75.2,
  "avgRelevance": 68.3
}

string

Unique competitor identifier

name

string

Competitor display name

domain

string

Competitor’s primary domain

relationship

string

Relationship type:

SELF: Your own brand
DIRECT: Direct competitor

totalMentions

number

Total number of times mentioned in AI responses

Percentage of total competitor mentions (0-100)

avgPosition

number

Average position when mentioned in lists (1 = first, lower is better)

avgSentiment

number

Average sentiment score (0-100, higher is more positive)

avgRelevance

number

Average relevance score (0-100, higher is more relevant)

Source

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

Related Endpoints

List Sources, Get Source Details, Source Evolution

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

string

Unique source identifier

domain

string

Source domain name

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

isSelf

boolean

Whether this source belongs to your brand

totalMentions

number

Total citations in AI responses

rate

number

Citation rate as percentage of all sources (0-100)

avgPosition

number

Average position in source lists (1 = first)

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.

Related Endpoints

List Prompts, Get Prompt Details, Prompt Answers

{
  "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"
}

string

Unique prompt identifier

text

string

The prompt/question text

topic

string

Associated topic/keyword name (can be null)

type

string

Marketing funnel stage:

TOFU: Top of Funnel (awareness)
MOFU: Middle of Funnel (consideration)
BOFU: Bottom of Funnel (decision)

Answer

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

Related Endpoints

List Answers, Get Answer Details

{
  "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,
  "relevance": 75,
  "createdAt": "2024-12-19T10:00:00.000Z"
}

string

Unique answer identifier

promptId

string

ID of the associated prompt

promptText

string

Text of the associated prompt

provider

string

AI provider name (ChatGPT, Perplexity, Claude, etc.)

model

string

Specific AI model used (GPT-4o, Sonar Large, etc.)

text

string

Full response text (or preview in list endpoints)

hasSelfMention

boolean

Whether your brand is mentioned

selfMentionPosition

number

Position in competitor list when mentioned (null if not mentioned)

hasSelfSource

boolean

Whether your domain is cited as a source

competitorsCount

number

Number of competitors mentioned in this answer

sourcesCount

number

Number of sources cited in this answer

sentiment

number

Sentiment score for your brand mention (0-100, null if not mentioned)

relevance

number

Relevance score for your brand mention (0-100, null if not mentioned)

createdAt

string

ISO 8601 timestamp of answer generation

CompetitorMention

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

{
  "name": "My Brand",
  "position": 3,
  "relationship": "SELF",
  "sentiment": 85,
  "relevance": 78
}

name

string

Competitor name as mentioned

position

number

Position in the response (1 = mentioned first)

relationship

string

SELF or DIRECT

sentiment

number

Sentiment score for this mention (0-100)

relevance

number

Relevance score for this mention (0-100)

SourceCitation

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

{
  "url": "https://industry-news.com/article",
  "domain": "industry-news.com",
  "position": 1,
  "isSelf": false
}

url

string

Full URL cited (can be null)

domain

string

Domain name of the source

position

number

Position in source list (1 = cited first)

isSelf

boolean

Whether this is your own domain

Topic

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

{
  "id": "topic_abc123",
  "name": "Product Reviews"
}

string

Unique topic identifier

name

string

Topic display name

Tag

Tags allow custom categorization of prompts.

{
  "id": "tag_xyz789",
  "name": "comparison"
}

string

Unique tag identifier

name

string

Tag display name

Evolution Data Point

Used in evolution endpoints to track metrics over time.

{
  "date": "2024-12-01",
  "mentions": 5,
  "shareOfVoice": 7.2,
  "avgPosition": 2.3,
  "avgSentiment": 76.5,
  "avgRelevance": 71.0
}

date

string

Date in YYYY-MM-DD format

mentions

number

Number of mentions on this date

Share of voice percentage on this date

avgPosition

number

Average position on this date

avgSentiment

number

Average sentiment on this date (competitors only)

avgRelevance

number

Average relevance on this date (competitors only)

Getting Started

Endpoints

​Pagination

​Pagination Example

​Brand

Related Endpoints

​Competitor

Related Endpoints

​Source

Related Endpoints

​Prompt

Related Endpoints

​Answer

Related Endpoints

​CompetitorMention

​SourceCitation

​Topic

​Tag

​Evolution Data Point

Pagination

Pagination Example

Brand

Competitor

Source

Prompt

Answer

CompetitorMention

SourceCitation

Topic

Tag

Evolution Data Point