Skip to content
TrakkrLearnAPI
Sign in

Diagnose

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

Code example

Run Diagnosis
curl -X POST 'https://api.trakkr.ai/diagnose' \
  -H "Authorization: Bearer $TRAKKR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"brand_id":"00000000-0000-4000-8000-81f286d10c3c","query":"best project management tools for remote teams","market_id":"11111111-1111-4111-8111-111111111111","idempotency_key":"550e8400-e29b-41d4-a716-446655440000"}'
Completed Result · 200 OK
{
  "id": "diag_abc123xyz",
  "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
  "query": "best project management tools for remote teams",
  "location": "GB",
  "market_id": "11111111-1111-4111-8111-111111111111",
  "market_scope": "exact",
  "status": "completed",
  "visibility_score": 45.0,
  "best_position": 3,
  "model_positions": {
    "chatgpt": 3,
    "claude": 5,
    "gemini": null,
    "perplexity": 2
  },
  "competitors": [
    {"name": "Asana", "positions": {"chatgpt": 1, "claude": 2}, "score": 85.0},
    {"name": "Monday.com", "positions": {"chatgpt": 2, "claude": 1}, "score": 82.0}
  ],
  "confidence_score": 72,
  "confidence_level": "High",
  "recommendations": [
    {
      "id": "rec_001",
      "title": "Create comparison page vs Asana",
      "gap": "Missing direct comparison content",
      "effort": "medium",
      "impact": "high",
      "validation_status": "SUPPORTED",
      "confidence": "high",
      "mentioned_by_models": 3
    }
  ],
  "summary": "Notion appears in AI answers but rarely in the top two positions...",
  "visibility_change": 5.0,
  "created_at": "2026-03-07T10:00:00Z",
  "completed_at": "2026-03-07T10:00:45Z",
  "duration_ms": 45000,
  "credits_used": 4,
  "models_queried": ["chatgpt", "claude", "gemini", "perplexity"],
  "models_succeeded": ["chatgpt", "claude", "perplexity"],
  "models_failed": ["gemini"]
}

Synthetic example. Values are made up.

API key required

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.

Authenticate with Authorization: Bearer $TRAKKR_API_KEY. Key and access guide

JSON request body (required)

brand_idstringRequired

Format: uuid

querystringRequired

The search query to diagnose

Minimum length: 3 · Maximum length: 500

market_idstring | nullOptional

Exact brand market id. Null selects Global.

idempotency_keystring | nullOptional

Stable key for retries, including after completion. If omitted, identical requests reuse an active run and start a new run after it finishes.

Minimum length: 8 · Maximum length: 128

Responses and errors
200Successful Response

application/json

diagnosis_idstringRequired

statusstringOptional

Default: "pending"

messagestringOptional

Default: "Diagnosis started"

outcomestringOptional

Default: "admitted" · Options: "admitted", "existing"

market_idstring | nullOptional

market_scopestringOptional

Default: "global" · Options: "exact", "global"

401Missing, malformed, or expired credentials

application/json

detailstring | object | nullOptional

errorstring | nullOptional

402The current plan does not fund this operation

application/json

detailstring | object | nullOptional

errorstring | nullOptional

403Invalid credentials, missing brand access, or insufficient role

application/json

detailstring | object | nullOptional

errorstring | nullOptional

422Validation Error

application/json

detailobject[]Optional

Fields in detail

Array of object.

locstring | integer[]Required

Fields in loc

Array of string | integer.

string

string.

integer

integer.

msgstringRequired

typestringRequired

429Rate limit exceeded

application/json

detailstring | object | nullOptional

errorstring | nullOptional

500The operation failed

application/json

detailstring | object | nullOptional

errorstring | nullOptional

503Authentication, entitlement, or a required dependency is temporarily unavailable

application/json

detailstring | object | nullOptional

errorstring | nullOptional

OpenAPI source
Response · 200 OK
{
  "diagnosis_id": "diag_abc123xyz",
  "status": "pending",
  "message": "Diagnosis started",
  "outcome": "admitted",
  "market_id": "11111111-1111-4111-8111-111111111111",
  "market_scope": "exact"
}

Synthetic example. Values are made up.

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

Get Result

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

Authenticate with Authorization: Bearer $TRAKKR_API_KEY. Key and access guide

Request parameters

brand_idstring | nullqueryOptional

Brand UUID (required for history/usage views)

Format: uuid

diagnosis_idstring | nullqueryOptional

Diagnosis ID to retrieve results

market_idstring | nullqueryOptional

Exact brand market id, 'global', or 'legacy'. Omit for all scopes.

viewstring | nullqueryOptional

View type: history or usage

Options: "history", "usage"

limitintegerqueryOptional

Max results for history view

Default: 20 · Minimum: 1 · Maximum: 100

Responses and errors
200Successful Response

application/json

DiagnoseResultApiResponse

idstringRequired

brand_idstringRequired

querystringRequired

locationstring | nullOptional

market_idstring | nullOptional

market_scopestringOptional

Default: "legacy" · Options: "exact", "global", "legacy"

statusstringRequired

error_messagestring | nullOptional

visibility_scorenumber | nullOptional

best_positioninteger | nullOptional

model_positionsobject | nullOptional

competitorsobject[] | nullOptional

model_consistency_scorenumber | nullOptional

hypothesis_factorsobject[] | nullOptional

confidence_scoreinteger | nullOptional

confidence_levelstring | nullOptional

recommendationsobject[] | nullOptional

summarystring | nullOptional

synthesis_summaryobject | nullOptional

variant_analysisobject[] | nullOptional

phrasing_insightobject | nullOptional

visibility_changenumber | nullOptional

created_atstringRequired

completed_atstring | nullOptional

duration_msinteger | nullOptional

credits_usedintegerOptional

Default: 4

models_queriedstring[] | nullOptional

models_succeededstring[] | nullOptional

models_failedstring[] | nullOptional

DiagnoseHistoryApiResponse

diagnosesobject[]Required

Fields in diagnoses

Array of object.

idstringRequired

querystringRequired

locationstring | nullOptional

market_idstring | nullOptional

market_scopestringOptional

Default: "legacy" · Options: "exact", "global", "legacy"

visibility_scorenumber | nullOptional

best_positioninteger | nullOptional

statusstringRequired

created_atstringRequired

visibility_changenumber | nullOptional

DiagnoseUsageApiResponse

usedintegerRequired

limitintegerRequired

remainingintegerRequired

401Missing, malformed, or expired credentials

application/json

detailstring | object | nullOptional

errorstring | nullOptional

402The current plan does not fund this operation

application/json

detailstring | object | nullOptional

errorstring | nullOptional

403Invalid credentials, missing brand access, or insufficient role

application/json

detailstring | object | nullOptional

errorstring | nullOptional

422Validation Error

application/json

detailobject[]Optional

Fields in detail

Array of object.

locstring | integer[]Required

Fields in loc

Array of string | integer.

string

string.

integer

integer.

msgstringRequired

typestringRequired

429Rate limit exceeded

application/json

detailstring | object | nullOptional

errorstring | nullOptional

500The operation failed

application/json

detailstring | object | nullOptional

errorstring | nullOptional

503Authentication, entitlement, or a required dependency is temporarily unavailable

application/json

detailstring | object | nullOptional

errorstring | nullOptional

OpenAPI source

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
curl -X GET 'https://api.trakkr.ai/diagnose?brand_id=00000000-0000-4000-8000-81f286d10c3c&view=history&limit=10' \
  -H "Authorization: Bearer $TRAKKR_API_KEY"
Response · 200 OK
{
  "diagnoses": [
    {
      "id": "diag_abc123xyz",
      "query": "best project management tools for remote teams",
      "location": "GB",
      "market_id": "11111111-1111-4111-8111-111111111111",
      "market_scope": "exact",
      "visibility_score": 45.0,
      "best_position": 3,
      "status": "completed",
      "created_at": "2026-03-07T10:00:00Z",
      "visibility_change": 5.0
    }
  ]
}

Synthetic example. Values are made up.

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.

Check Usage
curl -X GET 'https://api.trakkr.ai/diagnose?brand_id=00000000-0000-4000-8000-81f286d10c3c&view=usage&limit=20' \
  -H "Authorization: Bearer $TRAKKR_API_KEY"
Response · 200 OK
{
  "used": 12,
  "limit": 200,
  "remaining": 188
}

Synthetic example. Values are made up.

Quick Reference

EndpointDescriptionRate Limit
POST/diagnose
Run new diagnosis10/min
GET/diagnose
Result / history / usage60/min