Brand visibility overview (the /performance headline)

curl --request POST \
  --url https://app.geoly.ai/api/v1/reports/overview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "time_range": "30d",
  "start_date": "<string>",
  "end_date": "<string>",
  "platform": "all",
  "topic_ids": [
    "<string>"
  ],
  "country": "<string>"
}
'

import requests

url = "https://app.geoly.ai/api/v1/reports/overview"

payload = {
    "time_range": "30d",
    "start_date": "<string>",
    "end_date": "<string>",
    "platform": "all",
    "topic_ids": ["<string>"],
    "country": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    time_range: '30d',
    start_date: '<string>',
    end_date: '<string>',
    platform: 'all',
    topic_ids: ['<string>'],
    country: '<string>'
  })
};

fetch('https://app.geoly.ai/api/v1/reports/overview', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "kpi_state": "ok",
    "window": {
      "time_range": "7d",
      "start_at": "2023-11-07T05:31:56Z",
      "end_at": "2023-11-07T05:31:56Z",
      "end_bounded": true
    },
    "platform": "<string>",
    "scope": {
      "active": true,
      "topic_ids": [
        "<string>"
      ],
      "country": "<string>",
      "collapsed": true
    },
    "kpi_caliber": {
      "mention_rate": "board",
      "share_of_voice": "board"
    },
    "kpi_caliber_pending": true,
    "has_prompts": true,
    "has_completed_records": true,
    "total_mentions": 1,
    "ranked_records": 1,
    "completed_records": 1,
    "share_of_voice": {
      "share_pct": 50,
      "brand_mentioned_records": 1,
      "total_mentioned_records": 1
    },
    "share_of_voice_state": "ok",
    "best_platform": {
      "platform_code": "<string>",
      "platform_name": "<string>",
      "visibility_score": 50
    },
    "worst_platform": {
      "platform_code": "<string>",
      "platform_name": "<string>",
      "visibility_score": 50
    },
    "platforms": [
      {
        "platform_code": "<string>",
        "platform_name": "<string>",
        "visibility_score": 50,
        "mention_rate_pct": 50,
        "citation_rate_pct": 50,
        "completed_records": 1,
        "mentioned_records": 1,
        "avg_position": 123,
        "total_mentions": 1
      }
    ],
    "visibility_score": 50,
    "mention_rate_pct": 50,
    "citation_rate_pct": 50,
    "avg_position": 123,
    "top3_rate_pct": 50
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "schema_conformant": true,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

Reports

Overview report

Visibility score, mention rate, citation rate, share of voice and the per-platform breakdown for the window — the same numbers as the in-app overview. Every number counts the brands you track (your own brand + the competitors you added) under the current configuration; rank is among tracked brands only. data.kpi_state tells whether the KPIs are computed (ok), there are no counted answers in the window (no_data), the first count is still running (computing — no numbers yet, not 0), or the filtered read failed (unavailable). GET with body payload — no resources created. Billed per call at the price in x-geoly-cost (the same as the matching GEOly MCP tool).

POST

api

reports

overview

Brand visibility overview (the /performance headline)

curl --request POST \
  --url https://app.geoly.ai/api/v1/reports/overview \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "time_range": "30d",
  "start_date": "<string>",
  "end_date": "<string>",
  "platform": "all",
  "topic_ids": [
    "<string>"
  ],
  "country": "<string>"
}
'

import requests

url = "https://app.geoly.ai/api/v1/reports/overview"

payload = {
    "time_range": "30d",
    "start_date": "<string>",
    "end_date": "<string>",
    "platform": "all",
    "topic_ids": ["<string>"],
    "country": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    time_range: '30d',
    start_date: '<string>',
    end_date: '<string>',
    platform: 'all',
    topic_ids: ['<string>'],
    country: '<string>'
  })
};

fetch('https://app.geoly.ai/api/v1/reports/overview', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "kpi_state": "ok",
    "window": {
      "time_range": "7d",
      "start_at": "2023-11-07T05:31:56Z",
      "end_at": "2023-11-07T05:31:56Z",
      "end_bounded": true
    },
    "platform": "<string>",
    "scope": {
      "active": true,
      "topic_ids": [
        "<string>"
      ],
      "country": "<string>",
      "collapsed": true
    },
    "kpi_caliber": {
      "mention_rate": "board",
      "share_of_voice": "board"
    },
    "kpi_caliber_pending": true,
    "has_prompts": true,
    "has_completed_records": true,
    "total_mentions": 1,
    "ranked_records": 1,
    "completed_records": 1,
    "share_of_voice": {
      "share_pct": 50,
      "brand_mentioned_records": 1,
      "total_mentioned_records": 1
    },
    "share_of_voice_state": "ok",
    "best_platform": {
      "platform_code": "<string>",
      "platform_name": "<string>",
      "visibility_score": 50
    },
    "worst_platform": {
      "platform_code": "<string>",
      "platform_name": "<string>",
      "visibility_score": 50
    },
    "platforms": [
      {
        "platform_code": "<string>",
        "platform_name": "<string>",
        "visibility_score": 50,
        "mention_rate_pct": 50,
        "citation_rate_pct": 50,
        "completed_records": 1,
        "mentioned_records": 1,
        "avg_position": 123,
        "total_mentions": 1
      }
    ],
    "visibility_score": 50,
    "mention_rate_pct": 50,
    "citation_rate_pct": 50,
    "avg_position": 123,
    "top3_rate_pct": 50
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "schema_conformant": true,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

{
  "error": {
    "code": "INVALID_BODY",
    "message": "<string>",
    "details": {}
  },
  "meta": {
    "request_id": "<string>",
    "report": "<string>",
    "duration_ms": 123,
    "quota": {
      "cost": 123,
      "unlimited": true,
      "remaining": 123,
      "resets_at": "2023-11-07T05:31:56Z",
      "charge": "charged",
      "min_fee_reason": "missing_locale"
    }
  }
}

Authorizations

Authorization

string

header

required

API key from Settings → Developer → API keys (prefix geom_). Each key is bound to one brand.

Body

application/json

time_range

enum<string>

default:30d

Rolling window, or "custom" with start_date + end_date.

Available options:

7d,

30d,

90d,

180d,

custom

start_date

string

Start of a custom window (UTC+8 business day, YYYY-MM-DD).

Pattern: ^\d{4}-\d{2}-\d{2}$

end_date

string

End of a custom window (UTC+8 business day, YYYY-MM-DD).

Pattern: ^\d{4}-\d{2}-\d{2}$

platform

enum<string>

default:all

AI platform, or "all".

Available options:

all,

chatgpt,

perplexity,

gemini,

google_ai,

copilot,

google_ai_overview

topic_ids

string[]

Restrict to these topic ids (1–50). "_none" = prompts without a topic.

Required array length: 1 - 50 elements

Required string length: 1 - 64

country

string

ISO-2 country code of the prompts (e.g. US). Must be a country the brand has prompts in.

Required string length: 1 - 8

Response

The overview report. data follows OverviewReport when meta.schema_conformant is true.

data

object

required

The overview report. null only when meta.schema_conformant is false and the report output could not be mapped.

Option 1
Option 2
Option 3
Option 4

Show child attributes

Get started

Account

Catalog

Records

Reports

Overview report

Authorizations

Body

Response