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. Enterprise plans have unlimited diagnoses. Check your remaining quota 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)

200 OK

1{
2  "diagnosis_id": "diag_abc123xyz",
3  "status": "pending",
4  "message": "Diagnosis started"
5}

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)

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

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.

Get History

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      "visibility_score": 45.0,
7      "best_position": 3,
8      "status": "completed",
9      "created_at": "2026-03-07T10:00:00Z",
10      "visibility_change": 5.0
11    }
12  ]
13}

Check Usage

Use view=usage to check your monthly diagnosis quota. Returns -1 for limit and remaining when on an unlimited plan.

Check Usage

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": 25,
4  "remaining": 13
5}

Quick Reference

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

Code Example

Run Diagnosis

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": "75ffdeb9-0924-4ff9-8ded-c2470d73d224",
6    "query": "best project management tools for remote teams"
7  }'

200 OK

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

Run Diagnosis

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": "75ffdeb9-0924-4ff9-8ded-c2470d73d224",
6    "query": "best project management tools for remote teams"
7  }'

200 OK

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