Entities

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": [ ... ]
}

object

Show Pagination object

number

Total number of items matching the query (across all pages)

number

Number of items returned in this response

number

Maximum items per page (as requested or default)

number

Number of items skipped (for pagination)

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)

string

Brand display name

string

Primary domain associated with the brand

string

Optional brand description (can be null)

string

ISO 8601 timestamp of brand creation

object

Show Brand statistics

number

Total prompts tracked for this brand

number

Total AI responses analyzed

number

Number of competitors (SELF + DIRECT)

Pitch Audit

A Pitch Audit is a read-only report resource generated for an agency prospect. Once completed, its evidence is a snapshot. Competitor and co-competitor reports are subject views derived from the same audit, not separate audit records.

Related Endpoints

List Pitch Audits, Get Pitch Audit, Get Pitch Audit Subject Report

{
  "id": "8a218180-6dd7-43c7-a481-f6a1cc72dfd8",
  "status": "COMPLETED",
  "reportSubject": {
    "id": "self",
    "name": "Prospect Brand",
    "isOriginalBrand": true
  },
  "availableSubjects": [
    { "id": "self", "name": "Prospect Brand", "isOriginalBrand": true },
    { "id": "rival.com", "name": "Rival", "isOriginalBrand": false }
  ],
  "answersIncluded": false,
  "answerCount": 24,
  "coCompetitors": [
    {
      "subjectId": "rival.com",
      "name": "Rival",
      "scores": { "geoScore": 64, "mentionRate": 50 },
      "reportUrl": "/api/v1/pitch-audits/8a218180-6dd7-43c7-a481-f6a1cc72dfd8/reports/rival.com"
    }
  ]
}

object

Subject represented by the current report. The original prospect uses self; derived reports use a stable competitor subjectId.

array

All subjects that can be resolved within this audit.

array

Brands that appear in the same answers as the current subject. Use each row’s subjectId or canonical reportUrl to open its derived report. When includeCoCompetitorScores=true, each row also includes its full scores summary.

boolean

Whether the response contains full AI answer text. Answers are excluded by default.

number

Number of answers available, whether or not answer text was requested.

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
}

string

Unique competitor identifier

string

Competitor display name

string

Competitor’s primary domain

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.

number

Total number of times mentioned in AI responses

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.

number

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

number

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

Source

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

Related Endpoints

Source Domains, Source URLs, 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

string

Source domain name

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

boolean

Whether this source belongs to your brand

number

Total citations in AI responses

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.

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

string

The prompt/question text

string

Associated topic/keyword name (can be null)

string

Marketing funnel stage:

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

array

List of tag names for organization

number

Number of AI responses generated for this prompt

number

Percentage of answers mentioning your brand (0-100)

number

Percentage of answers citing your domain (0-100)

string

ISO 8601 timestamp of last answer generation

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

string

Unique answer identifier

string

ID of the associated prompt

string

Text of the associated prompt

string

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

string

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

string

Full response text (or preview in list endpoints)

boolean

Whether your brand is mentioned

number

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

boolean

Whether your domain is cited as a source

number

Number of competitors mentioned in this answer

number

Number of sources cited in this answer

number

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

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
}

string

Competitor name as mentioned

number

Position in the response (1 = mentioned first)

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.

number

Sentiment 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
}

string

Full URL cited (can be null)

string

Domain name of the source

number

Position in source list (1 = cited first)

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

string

Topic display name

Tag

Tags allow custom categorization of prompts.

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

string

Unique tag identifier

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
}

string

Date in YYYY-MM-DD format

number

Number of mentions on this date

Share of voice percentage on this date

number

Average position on this date

number

Average sentiment on this date (competitors only)

Getting Started

Setup

Cockpit

Monitor

Analyze

Act

Optimize

Agencies

Webhooks

Guides

Brand

Related Endpoints

Pitch Audit

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

Related Endpoints

​Pitch Audit

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

Pitch Audit

Competitor

Source

Prompt

Answer

CompetitorMention

SourceCitation

Topic

Tag

Evolution Data Point