Skip to main content
This quickstart walks you through the complete lifecycle of an EyeQuant analysis: submitting a URL for processing, polling for the result, and downloading the visual attention heatmap the API produces. By the end, you will have made real API calls and seen a working response — a solid foundation for integrating EyeQuant into your own application.

​
Prerequisites

Before you begin, make sure you have your EyeQuant API key available. If you do not have one yet, see the Authentication page for details on how to obtain credentials.
1

Submit an analysis

Send a POST request to /v2/analyses to kick off a new analysis. In the request body, specify the type of input you are providing. For this quickstart, you will analyze the Google homepage using the webPageUrl input type on a desktopWeb medium — this instructs the API to take a desktop-browser screenshot of the URL and run the full attention analysis pipeline on it.Replace $apikey with your actual API key before running this command:
curl \
  -X POST \
  -H "Authorization: Bearer $apikey" \
  -H "Content-Type: application/json" \
  -d '{
        "input": {
          "type": "webPageUrl",
          "content": "http://www.google.com",
          "medium": "desktopWeb",
          "title": "My First Analysis"
        }
      }' \
  https://api.eyequant.com/v2/analyses
A successful submission returns an HTTP 201 Created response with the new analysis ID and a location URL you will use in the next step:
{
  "location": "https://api.eyequant.com/v2/analyses/611457618c1d4283a830d10a9ad4f8ae",
  "id": "611457618c1d4283a830d10a9ad4f8ae"
}
Save the id value — you will need it to poll for results.
2

Poll for results

Taking a screenshot and running the attention model both take time, so analyses are processed asynchronously. Retrieve the analysis by making a GET request to /v2/analyses/{id} using the ID returned in the previous step:
curl \
  -X GET \
  -H "Authorization: Bearer $apikey" \
  https://api.eyequant.com/v2/analyses/611457618c1d4283a830d10a9ad4f8ae
While the analysis is still running, the response status will be pending:
{ "id": "611457618c1d4283a830d10a9ad4f8ae", "status": "pending" }
Keep polling the same endpoint until the status changes. Once the analysis completes successfully, the response includes an outputs object containing links to the generated maps:
{
  "id": "611457618c1d4283a830d10a9ad4f8ae",
  "status": "success",
  "outputs": {
    "attention": {
      "attentionMap": "https://s3.amazonaws.com/api-eyequant/attentionHeatmap.png"
    }
  }
}
Poll the results endpoint every few seconds rather than hammering it in a tight loop. For pages that require a full screenshot and render cycle, analyses can take 10–30 seconds to complete. A 5-second polling interval is a reasonable starting point for most use cases.
3

Download and store the heatmap

The attentionMap URL in the outputs object points directly to the generated heatmap image hosted on AWS S3. Download it using a standard HTTP GET — no additional Authorization header is needed, because the URL already contains a time-limited access token:
curl -o attentionHeatmap.png \
  "https://s3.amazonaws.com/api-eyequant/attentionHeatmap.png"
Store the downloaded image and any other output data on your own infrastructure as soon as possible. Output URLs are time-limited and will expire — the EyeQuant API does not guarantee long-term availability of these links.

​
Next steps

You have just completed a full analysis using a web page URL. EyeQuant supports additional input types and media modes to cover a wide range of use cases:
  • Uploaded images — Submit a base64-encoded PNG or JPEG using the image input type to analyze static designs or assets that are not publicly hosted.
  • Mobile and generic viewports — Swap "medium": "desktopWeb" for "medium": "mobileWeb" or "medium": "generic" to simulate different viewing contexts.
  • Video analysis — Upload a video file using GET /v2/upload-urls to obtain a presigned upload URL, then submit the analysis via POST /v2/analyses/video.
Head over to the Guides section to explore all available input types and learn how to get the most out of the attention, clarity, and excitingness outputs.