Score Lookup API
TL;DR
The Score Lookup API lets you retrieve the most recent AI readiness score for any domain that has been scanned before. No new scan is triggered — you get instant results from the database.
Last updated: 2026-03-09
Endpoint Overview#
The Score Lookup API returns the most recent scan results for a given domain without triggering a new scan. This is useful for dashboards, status pages, or integrations where you want to display a site's current AI readiness score without waiting for a full analysis.
If the domain has never been scanned, the API returns a
404 response. In that case, use the Scan API to run an initial scan first.Score Lookup Endpoint
GET /api/score?domain=example.comhttp
Query Parameters#
The score lookup endpoint uses simple query parameters to identify the domain and control what data is returned.
domain(string, required) — The domain name to look up. Do not include the protocol or path (useexample.com, nothttps://example.com/page).history(boolean, optional) — Iftrue, returns all historical scan scores for the domain, not just the latest. Default:false.fields(string, optional) — Comma-separated list of fields to include. Use this to reduce response size. Example:overallScore,grade,subScores.
Response Format#
The response mirrors the scan result format — overall score, grade, sub-scores, and metadata. When
history=true, the response includes an array of all previous scans with timestamps, allowing you to chart score changes over time.
The lookup is instant because it reads from the database. No crawling or analysis is performed. This makes it ideal for high-frequency polling or embedding score badges on external sites.Response Example
{
"domain": "example.com",
"latestScan": {
"id": "scan_abc123",
"date": "2026-03-08T14:30:00Z",
"overallScore": 72,
"grade": "B+",
"subScores": {
"schemaMarkup": 65,
"contentQuality": 80,
"botAccess": 90,
"topicClarity": 55,
"aiProtocols": 40,
"speedPerformance": 85,
"authorityTrust": 60,
"crawlHealth": 75
},
"algorithmVersion": "2.0"
}
}json
Tracking Score History#
When you pass
history=true, the response includes an array of all scans for the domain ordered by date. Each entry contains the overall score, grade, and algorithm version used at the time of the scan.
This is valuable for tracking improvements over time. After implementing changes from the fix guides, you can chart your score trajectory to verify that each round of optimizations had the expected impact. Agencies can use this data to build client progress reports showing measurable improvement.Related Pages
Frequently Asked Questions
What happens if the domain has never been scanned?
The API returns a 404 response with an error message indicating that no scan data exists for that domain. You can then use the Scan API to trigger an initial scan.
Does a score lookup count against my rate limit?
Score lookups are significantly cheaper than full scans in terms of rate limiting. They do count toward your API usage, but at a much lower cost. Check your plan details for specific lookup limits.
Was this page helpful?