Skip to main content
Retrieve a single analysis by its ID. Use this endpoint to check processing status and fetch scores, per-criterion breakdowns, and AI-generated feedback once the analysis completes.

​
Endpoint

GET https://api.screenscoreai.com/v1/analyses/{id}

​
Path parameters

​
id
string
required
The analysis ID to retrieve. Analysis IDs are prefixed ana_.

​
Example request

curl --request GET \
  --url https://api.screenscoreai.com/v1/analyses/ana_09jz7p3nqwec1x5vbr4mt8ks2d \
  --header "Authorization: Bearer YOUR_API_KEY"
If the analysis status is pending or processing, scoring is still in progress and score, breakdown, and feedback will be null. Poll this endpoint every 2–5 seconds until status changes to completed or failed. For production integrations, consider using webhooks instead — they push a notification to your server the moment scoring finishes, eliminating the need to poll.

​
Response

​
id
string
required
Unique identifier for this analysis, prefixed ana_.
​
project_id
string
required
The ID of the project this analysis belongs to.
​
status
string
required
Current processing status. One of pending, processing, completed, or failed.
​
image_url
string
The URL of the image that was analyzed. null if the image was submitted as base64 data.
​
label
string
The label provided at creation time. null if no label was supplied.
​
score
number
Overall score from 0 to 100. null until status is completed.
​
breakdown
object
Per-criterion scores. null until status is completed.
​
feedback
string[]
List of actionable suggestions generated by the AI. null until status is completed.
​
error_message
string
Human-readable description of what went wrong. Populated only when status is failed, otherwise null.
​
created_at
string
required
ISO 8601 timestamp of when the analysis was created.
​
completed_at
string
ISO 8601 timestamp of when scoring finished. null until status is completed or failed.

​
Example response (completed)

{
  "id": "ana_09jz7p3nqwec1x5vbr4mt8ks2d",
  "project_id": "proj_01hx4k2m9fvbzq3rcw7ndj6e5t",
  "status": "completed",
  "image_url": "https://example.com/screens/homepage-v2.png",
  "label": "Homepage - Variant B",
  "score": 78,
  "breakdown": {
    "visual_clarity": 82,
    "visual_hierarchy": 74,
    "color_contrast": 91,
    "cta_effectiveness": 65,
    "brand_consistency": 80
  },
  "feedback": [
    "The primary CTA button lacks sufficient contrast with the background — consider increasing its size or switching to a higher-contrast color.",
    "Text hierarchy between the headline and subheading is too similar in weight; differentiate them more clearly to guide the user's eye.",
    "Strong use of whitespace throughout — this improves scannability and keeps the layout feeling uncluttered."
  ],
  "error_message": null,
  "created_at": "2026-04-16T10:23:45Z",
  "completed_at": "2026-04-16T10:23:52Z"
}