Diagnose

Run AI-powered query diagnostics to understand why your brand does or doesn't appear in AI search results.

Requires authentication

Monthly quota10 req/min

Overview

Diagnose analyzes why your brand does or doesn't appear for a specific search query across AI models. It queries ChatGPT, Claude, Gemini, and Perplexity, then provides competitor analysis, hypothesis factors, and prioritized recommendations.

Diagnose has a monthly usage quota of 200 diagnoses per month on the Scale plan. Every plan has a fixed monthly number; there is no unlimited tier. Check what you have left with the view=usage parameter.

Run Diagnosis

POST/diagnoseStart a new diagnosis. Returns immediately with a diagnosis_id to poll.

Body Parameters

brand_idstringrequired

The brand ID to diagnose

querystringrequired

The search query to diagnose (3-500 characters)

market_idstring

Exact brand market ID. Omit or pass null for Global.

idempotency_keystringrequired

Stable unique key for this logical launch. Reuse it when retrying an uncertain request.

200 OK

1{
2  "diagnosis_id": "diag_abc123xyz",
3  "status": "pending",
4  "message": "Diagnosis started",
5  "outcome": "admitted",
6  "market_id": "11111111-1111-4111-8111-111111111111",
7  "market_scope": "exact"
8}

Diagnosis runs asynchronously and takes 30-60 seconds. PollGET /diagnose?diagnosis_id=Xevery 3 seconds until status is "completed" or "failed".

Get Result

GET/diagnoseGet diagnosis results, history, or usage quota.

Query Parameters

diagnosis_idstring

Get a specific diagnosis result (for polling)

brand_idstring

Brand ID (required for history and usage views)

market_idstring

Exact market ID, or "global". Omit for all scopes.

viewstring

"history" or "usage". Defaults to history when brand_id is provided.

limitinteger

Max results for history view (1-100)

Default: 20

The Diagnosis Object

Diagnosis Schema

idstring

Unique diagnosis identifier

statusstring

"pending", "running", "validating", "completed", or "failed"

querystring

The search query that was diagnosed

market_idstringnullable

Exact brand market ID

market_scopestring

"exact", "global", or "legacy"

visibility_scorefloatnullable

Visibility score for this query (0-100)

best_positionintegernullable

Best rank across all AI models

model_positionsobjectnullable

Position per model: {chatgpt: 3, claude: null, ...}

competitorsarraynullable

Top competitors with positions and scores

confidence_scoreintegernullable

Confidence in the diagnosis (0-100)

confidence_levelstringnullable

"High", "Medium", or "Low"

recommendationsarraynullable

Prioritized recommendations with effort and impact

summarystringnullable

One-sentence narrative summary

visibility_changefloatnullable

Change vs previous diagnosis of the same query

duration_msintegernullable

Time taken in milliseconds

models_succeededstring[]nullable

Models that returned results

models_failedstring[]nullable

Models that failed or timed out

View History

Use view=history to list past diagnoses for a brand. Results are deduplicated by query, showing only the most recent diagnosis per unique query.

1curl -H 'Authorization: Bearer $TRAKKR_API_KEY' \
2  'https://api.trakkr.ai/diagnose?brand_id=YOUR_BRAND_ID&view=history&limit=10'

200 OK

1{
2  "diagnoses": [
3    {
4      "id": "diag_abc123xyz",
5      "query": "best project management tools for remote teams",
6      "location": "GB",
7      "market_id": "11111111-1111-4111-8111-111111111111",
8      "market_scope": "exact",
9      "visibility_score": 45.0,
10      "best_position": 3,
11      "status": "completed",
12      "created_at": "2026-03-07T10:00:00Z",
13      "visibility_change": 5.0
14    }
15  ]
16}

Check Usage

Use view=usage to check your monthly diagnosis quota. The count runs per brand and resets on the first of the month. limit is always a number, and remaining never goes below zero.

1curl -H 'Authorization: Bearer $TRAKKR_API_KEY' \
2  'https://api.trakkr.ai/diagnose?brand_id=YOUR_BRAND_ID&view=usage'

200 OK

1{
2  "used": 12,
3  "limit": 200,
4  "remaining": 188
5}

Quick Reference

Endpoint	Description	Rate Limit
POST`/diagnose`	Run new diagnosis	10/min
GET`/diagnose`	Result / history / usage	60/min

Code example

1curl -X POST 'https://api.trakkr.ai/diagnose' \
2  -H 'Authorization: Bearer $TRAKKR_API_KEY' \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
6    "query": "best project management tools for remote teams",
7    "market_id": "11111111-1111-4111-8111-111111111111",
8    "idempotency_key": "550e8400-e29b-41d4-a716-446655440000"
9  }'

200 OK

1{
2  "id": "diag_abc123xyz",
3  "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
4  "query": "best project management tools for remote teams",
5  "location": "GB",
6  "market_id": "11111111-1111-4111-8111-111111111111",
7  "market_scope": "exact",
8  "status": "completed",
9  "visibility_score": 45.0,
10  "best_position": 3,
11  "model_positions": {
12    "chatgpt": 3,
13    "claude": 5,
14    "gemini": null,
15    "perplexity": 2
16  },
17  "competitors": [
18    {"name": "Asana", "positions": {"chatgpt": 1, "claude": 2}, "score": 85.0},
19    {"name": "Monday.com", "positions": {"chatgpt": 2, "claude": 1}, "score": 82.0}
20  ],
21  "confidence_score": 72,
22  "confidence_level": "High",
23  "recommendations": [
24    {
25      "id": "rec_001",
26      "title": "Create comparison page vs Asana",
27      "gap": "Missing direct comparison content",
28      "effort": "medium",
29      "impact": "high",
30      "validation_status": "SUPPORTED",
31      "confidence": "high",
32      "mentioned_by_models": 3
33    }
34  ],
35  "summary": "Notion appears in 3 of 4 AI models but rarely in the top 2 positions...",
36  "visibility_change": 5.0,
37  "created_at": "2026-03-07T10:00:00Z",
38  "completed_at": "2026-03-07T10:00:45Z",
39  "duration_ms": 45000,
40  "credits_used": 4,
41  "models_queried": ["chatgpt", "claude", "gemini", "perplexity"],
42  "models_succeeded": ["chatgpt", "claude", "perplexity"],
43  "models_failed": ["gemini"]
44}

1curl -X POST 'https://api.trakkr.ai/diagnose' \
2  -H 'Authorization: Bearer $TRAKKR_API_KEY' \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
6    "query": "best project management tools for remote teams",
7    "market_id": "11111111-1111-4111-8111-111111111111",
8    "idempotency_key": "550e8400-e29b-41d4-a716-446655440000"
9  }'

200 OK

1{
2  "id": "diag_abc123xyz",
3  "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
4  "query": "best project management tools for remote teams",
5  "location": "GB",
6  "market_id": "11111111-1111-4111-8111-111111111111",
7  "market_scope": "exact",
8  "status": "completed",
9  "visibility_score": 45.0,
10  "best_position": 3,
11  "model_positions": {
12    "chatgpt": 3,
13    "claude": 5,
14    "gemini": null,
15    "perplexity": 2
16  },
17  "competitors": [
18    {"name": "Asana", "positions": {"chatgpt": 1, "claude": 2}, "score": 85.0},
19    {"name": "Monday.com", "positions": {"chatgpt": 2, "claude": 1}, "score": 82.0}
20  ],
21  "confidence_score": 72,
22  "confidence_level": "High",
23  "recommendations": [
24    {
25      "id": "rec_001",
26      "title": "Create comparison page vs Asana",
27      "gap": "Missing direct comparison content",
28      "effort": "medium",
29      "impact": "high",
30      "validation_status": "SUPPORTED",
31      "confidence": "high",
32      "mentioned_by_models": 3
33    }
34  ],
35  "summary": "Notion appears in 3 of 4 AI models but rarely in the top 2 positions...",
36  "visibility_change": 5.0,
37  "created_at": "2026-03-07T10:00:00Z",
38  "completed_at": "2026-03-07T10:00:45Z",
39  "duration_ms": 45000,
40  "credits_used": 4,
41  "models_queried": ["chatgpt", "claude", "gemini", "perplexity"],
42  "models_succeeded": ["chatgpt", "claude", "perplexity"],
43  "models_failed": ["gemini"]
44}