Qwairy

https://docs.qwairy.co/
Admin
Qwairy is a strategic tool designed to monitor and improve how brands are represented in AI-powered...
Tokens:204,352
Snippets:2,248
Trust Score:7.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Example Shopping Insights Request

Source: https://docs.qwairy.co/api-reference/endpoints/shopping

This example demonstrates how to make a GET request to the shopping insights endpoint, including authentication and query parameters for limiting results.

```bash
curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/shopping?limit=10" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

--------------------------------

### Example Prompts for get_competitor_evolution

Source: https://docs.qwairy.co/mcp/tools/competitors

Offers example natural language queries for tracking competitor performance trends over a specified period.

```text
How has CompetitorA trended over the last month?
```

```text
Is CompetitorB gaining or losing visibility?
```

```text
Show me the evolution of my own brand mentions
```

--------------------------------

### Example Request for Sponsored Content

Source: https://docs.qwairy.co/api-reference/endpoints/sponsored

This example demonstrates how to make a GET request to the sponsored content endpoint using curl. It includes a brand ID, a specified period, and a limit for the number of results. Replace 'cm1234567890abcdef' with your actual brand ID and 'qw-api-your-token-here' with your API token.

```bash
curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/sponsored?period=30&limit=10" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

--------------------------------

### List Source URLs cURL Example

Source: https://docs.qwairy.co/api-reference/endpoints/source-urls

Example using cURL to fetch source URLs, demonstrating how to include authorization and query parameters like 'isSelf' and 'limit'.

```bash
curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/source-urls?isSelf=true&limit=10" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

--------------------------------

### Example Prompts for get_competitors

Source: https://docs.qwairy.co/mcp/tools/competitors

Provides example natural language prompts that can be used to query competitor information using the `get_competitors` function.

```text
Who are my competitors in AI responses?
```

```text
Show me only direct competitors
```

```text
Which brands appear alongside mine most often?
```

--------------------------------

### Example Prompts for get_prompts

Source: https://docs.qwairy.co/mcp/tools/responses

Illustrates natural language queries that can be used to retrieve prompt information. These examples show how to ask for all prompts, filter by type, or filter by tag.

```text
What prompts am I monitoring?
```

```text
Show me my BOFU queries
```

```text
List prompts with the "pricing" tag
```

--------------------------------

### Example Prompts for get_prompt_answers

Source: https://docs.qwairy.co/mcp/tools/responses

Provides example natural language queries for retrieving AI responses. These demonstrate how to ask for general answers, filter by provider, or compare responses across different AIs.

```text
How do AI providers answer "best project management software"?
```

```text
Show me ChatGPT's response to my pricing query
```

```text
Compare how different AIs respond to this prompt
```

--------------------------------

### Example Prompts for get_source_urls

Source: https://docs.qwairy.co/mcp/tools/sources

Provides example natural language queries to retrieve specific URL information cited by AI using the `get_source_urls` tool.

```text
What specific pages are AI providers citing?
```

```text
Which of my pages get cited most?
```

```text
Show me URLs from wikipedia.org that are being cited
```

```text
What Reddit threads are being cited?
```

--------------------------------

### Example Prompts for get_source_domains

Source: https://docs.qwairy.co/mcp/tools/sources

Provides example natural language queries to retrieve specific information about AI-cited sources using the `get_source_domains` tool.

```text
Which sources do AI providers cite most often?
```

```text
Is my domain being cited as a source?
```

```text
Show me media sources only
```

```text
What forums are being cited for my topics?
```

--------------------------------

### Example Response for Get Source Domain

Source: https://docs.qwairy.co/api-reference/endpoints/source-domains/get

This JSON object represents a successful response from the Get Source Domain API, detailing source information, mentions, and performance metrics broken down by provider and topic.

```json
{
  "success": true,
  "source": {
    "id": "src1",
    "domain": "industry-news.com",
    "type": "MEDIA",
    "status": "ACTIVE",
    "isSelf": false,
    "totalMentions": 102,
    "rate": 5.10,
    "avgPosition": 3.2,
    "byProvider": [
      { "provider": "ChatGPT", "mentions": 60, "avgPosition": 3.1 },
      { "provider": "Perplexity", "mentions": 42, "avgPosition": 3.4 }
    ],
    "byTopic": [
      { "topic": "Product Reviews", "mentions": 55, "avgPosition": 2.8 },
      { "topic": "Comparisons", "mentions": 30, "avgPosition": 3.5 }
    ]
  }
}
```

--------------------------------

### Fetch and Export Data using Qwairy Client

Source: https://docs.qwairy.co/api-reference/guides/data-export

Demonstrates fetching data using the QwairyClient and exporting it to CSV and JSON files. Requires the QwairyClient to be initialized.

```python
client = QwairyClient()

# Fetch data
data = fetch_all_data(client, 'your-brand-id', period=30)

# Export to files
csv_result = export_to_csv(data)
print(f"CSV files: {csv_result['files']}")

json_result = export_to_json(data)
print(f"JSON file: {json_result['file']} ({json_result['size']} bytes)")

# Export to BigQuery (requires google-cloud-bigquery)
# bq_result = export_to_bigquery(data)
# print(f"BigQuery tables: {bq_result['tables']}")
```

--------------------------------

### Example cURL Request for Local Insights

Source: https://docs.qwairy.co/api-reference/endpoints/local

This example demonstrates how to make a GET request to the local insights endpoint using cURL. It includes filtering by category and setting a limit for the number of results, along with the necessary authorization header.

```bash
curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/local?category=restaurant&limit=10" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

--------------------------------

### Example Prompt: Get Cited Sources

Source: https://docs.qwairy.co/mcp/tools/responses

A natural language prompt to specifically query for the sources that were cited in a particular AI response.

```text
What sources were cited in that ChatGPT answer?
```

--------------------------------

### Example Prompt: Get Mentioned Competitors

Source: https://docs.qwairy.co/mcp/tools/responses

A natural language prompt to inquire about which competitors or brands were mentioned within a specific AI response.

```text
Who was mentioned in that response?
```

--------------------------------

### Example Prompt: Get Full Response Details

Source: https://docs.qwairy.co/mcp/tools/responses

A natural language prompt to retrieve all available details for a previously identified AI response.

```text
Show me the full details of that response
```

--------------------------------

### Credit Calculation Example

Source: https://docs.qwairy.co/documentation/get-started/faq

Illustrates how to calculate the total credits consumed for a monitoring run based on the number of prompts and the cost of selected AI models.

```text
Total credits = Number of prompts × Sum of credits per selected model
```

```text
Example: 30 prompts with ChatGPT (1) + Claude Sonnet 4 (3) + Perplexity (1) = 30 × 5 = 150 credits.
```

--------------------------------

### Example Prompt: Performance by Keyword

Source: https://docs.qwairy.co/mcp/tools/performance

A sample prompt to retrieve performance data broken down by specific keywords.

```text
Show me performance by keyword
```

--------------------------------

### GET Matrix Data Request

Source: https://docs.qwairy.co/api-reference/endpoints/matrix

Example of a cURL request to fetch matrix data for a specific brand. Specify granularity, period, and limit for the data retrieval.

```bash
curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/matrix?granularity=topics&period=30&limit=10" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

--------------------------------

### Get Brand Example

Source: https://docs.qwairy.co/api-reference/endpoints/brands/get

Use this cURL command to retrieve detailed information about a specific brand. Ensure you replace 'cm1234567890abcdef' with the actual brand ID and 'qw-api-your-token-here' with your valid bearer token.

```bash
curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

--------------------------------

### Example Output for get_prompt_answers

Source: https://docs.qwairy.co/mcp/tools/responses

Shows a sample response structure for AI answers to a specific prompt. Includes details like AI provider, model, creation date, and a preview of the response text. Useful for analyzing AI performance and content.

```markdown
## AI Responses for: "best project management software 2025"

Found 8 responses

### 1. ChatGPT (GPT-5)
Date: 2025-01-28
Brand mentioned: Yes
Sentiment: 82/100

Preview: "For project management in 2025, several excellent options stand out. **Acme Corp** offers robust features for team collaboration..."

### 2. Perplexity Pro
Date: 2025-01-28
Brand mentioned: No

Preview: "The top project management tools include Monday.com, Asana, and Notion. Each offers unique strengths..."

### 3. Claude (Sonnet)
Date: 2025-01-27
Brand mentioned: Yes
Sentiment: 79/100

Preview: "Based on recent reviews, I'd recommend considering **Acme Corp** for enterprise teams that need..."
```

--------------------------------

### Get Answer API Response

Source: https://docs.qwairy.co/api-reference/endpoints/answers/get

This is an example of a successful response when retrieving an answer. It includes the answer's ID, prompt details, AI provider and model, the full text, detected competitors, cited sources, sentiment score, and creation timestamp.

```json
{
  "success": true,
  "answer": {
    "id": "ans1",
    "prompt": {
      "id": "q1",
      "text": "What are the best products in this category?",
      "topic": "Product Reviews",
      "type": "TOFU"
    },
    "provider": "ChatGPT",
    "model": "GPT-4o",
    "text": "Based on recent reviews and comparisons, several products stand out in this category. My Brand offers one of the best solutions with excellent performance and user ratings. Competitor A also provides a strong alternative...",
    "competitors": [
      {
        "name": "My Brand",
        "position": 3,
        "relationship": "SELF",
        "sentiment": 85
      },
      {
        "name": "Competitor A",
        "position": 1,
        "relationship": "DIRECT",
        "sentiment": 80
      }
    ],
    "sources": [
      {
        "url": "https://industry-news.com/product-comparison",
        "domain": "industry-news.com",
        "position": 1,
        "isSelf": false
      },
      {
        "url": "https://mybrand.com/products",
        "domain": "mybrand.com",
        "position": 2,
        "isSelf": true
      }
    ],
    "sentiment": 82,
    "createdAt": "2024-12-19T10:00:00.000Z"
  }
}
```

--------------------------------

### Example Prompt: AI Brand Optimization Best Practices

Source: https://docs.qwairy.co/mcp/tools/documentation

A sample prompt to request best practices for AI brand optimization.

```text
What are the best practices for AI brand optimization?
```

--------------------------------

### Example API Response

Source: https://docs.qwairy.co/api-reference/endpoints/answers/list

This is an example of a successful JSON response when listing answers.

```json
{
  "success": true,
  "pagination": {
    "total": 312,
    "count": 1,
    "limit": 10,
    "offset": 0
  },
  "answers": [
    {
      "id": "ans1",
      "promptId": "q1",
      "promptText": "What are the best products in this category?",
      "provider": "ChatGPT",
      "model": "GPT-4o",
      "textPreview": "Based on recent reviews and comparisons, several products stand out in this category. My Brand offers one of the best solutions...",
      "hasSelfMention": true,
      "selfMentionPosition": 3,
      "hasSelfSource": false,
      "competitorsCount": 5,
      "sourcesCount": 3,
      "sentiment": 82,
      "createdAt": "2024-12-19T10:00:00.000Z"
    }
  ]
}
```

--------------------------------

### Get GEO Matrix

Source: https://docs.qwairy.co/llms.txt

Get the GEO visibility matrix for your brand across providers and dimensions.

```APIDOC
## Get GEO Matrix

### Description
Get the GEO visibility matrix for your brand across providers and dimensions.

### Endpoint
/api-reference/endpoints/matrix.md
```

--------------------------------

### Fetch and Export Data using Qwairy Client

Source: https://docs.qwairy.co/api-reference/guides/data-export

Demonstrates fetching data using the QwairyClient and exporting it to CSV and JSON files. Requires the QwairyClient to be initialized with an API token.

```javascript
const client = new QwairyClient(process.env.QWAIRY_API_TOKEN);

// Fetch data
const data = await fetchAllData(client, 'your-brand-id', 30);

// Export to files
const csvResult = exportToCSV(data);
console.log('CSV files:', csvResult.files);

const jsonResult = exportToJSON(data);
console.log('JSON file:', jsonResult.file, `(${jsonResult.size} bytes)`);

// Export to BigQuery (requires @google-cloud/bigquery)
// const bqResult = await exportToBigQuery(data);
// console.log('BigQuery tables:', bqResult.tables);
```

--------------------------------

### Error Handling Example (Python)

Source: https://docs.qwairy.co/api-reference/errors

Example code demonstrating how to handle various API errors in a Python application.

```APIDOC
## Handling Errors in Python

### Description
This example illustrates how to manage different types of API errors when interacting with the Qwairy API using Python's `requests` library.

### Code Example
```python
import requests
import os

def call_qwairy_api(endpoint):
    response = requests.get(
        f"https://www.qwairy.co/api/v1{endpoint}",
        headers={"Authorization": f"Bearer {os.environ['QWAIRY_API_TOKEN']}"}
    )

    if not response.ok:
        body = response.json() if response.content else {}

        # Auth and rate-limit errors use the flat shape: { error, message }
        if response.status_code == 401:
            raise Exception(f"Authentication failed: {body.get('message', body.get('error'))}")
        if response.status_code == 429:
            retry_after = body.get('retryAfter', response.headers.get('Retry-After'))
            raise Exception(f"Rate limited. Retry after: {retry_after}s")

        # Resource errors use the nested shape: { error: { code, message } }
        error = body.get('error', {}) if isinstance(body.get('error'), dict) else {}
        code = error.get('code', 'UNKNOWN')
        message = error.get('message', body.get('message', 'Unknown error'))

        if code in ['INSUFFICIENT_PLAN', 'FORBIDDEN']:
            raise Exception(f"Permission denied: {message}")
        elif code.endswith('_NOT_FOUND'):
            raise Exception(f"Not found: {message}")
        else:
            raise Exception(f"API error [{code}]: {message}")

    return response.json()
```
```

--------------------------------

### Error Handling Example (JavaScript/TypeScript)

Source: https://docs.qwairy.co/api-reference/errors

Example code demonstrating how to handle various API errors in a JavaScript or TypeScript application.

```APIDOC
## Handling Errors in JavaScript/TypeScript

### Description
This example shows how to implement robust error handling for Qwairy API calls in JavaScript or TypeScript, distinguishing between different error types and statuses.

### Code Example
```typescript
async function callQwairyAPI(endpoint: string) {
  const response = await fetch(`https://www.qwairy.co/api/v1${endpoint}`, {
    headers: {
      'Authorization': `Bearer ${process.env.QWAIRY_API_TOKEN}`,
    },
  });

  if (!response.ok) {
    const data = await response.json().catch(() => ({}));

    // Auth and rate-limit errors use the flat shape: { error, message }
    if (response.status === 401) {
      throw new Error(`Authentication failed: ${data.message ?? data.error}`);
    }
    if (response.status === 429) {
      const retryAfter = data.retryAfter ?? response.headers.get('Retry-After');
      throw new Error(`Rate limited. Retry after: ${retryAfter}s`);
    }

    // Resource errors use the nested shape: { error: { code, message } }
    const code = data.error?.code ?? 'UNKNOWN';
    const message = data.error?.message ?? data.message ?? `HTTP ${response.status}`;

    switch (code) {
      case 'INSUFFICIENT_PLAN':
      case 'FORBIDDEN':
        throw new Error(`Permission denied: ${message}`);
      case 'BRAND_NOT_FOUND':
      case 'COMPETITOR_NOT_FOUND':
      case 'SOURCE_NOT_FOUND':
      case 'PROMPT_NOT_FOUND':
      case 'ANSWER_NOT_FOUND':
        throw new Error(`Resource not found: ${message}`);
      default:
        throw new Error(`API error [${code}]: ${message}`);
    }
  }

  return response.json();
}
```
```
Tokens:
Raw