API reference

Analyze (AI)

AI insights: summary, value proposition, features, categories, use cases, audience and contact signals.

GEThttp://localhost:4000/v1/analyze

Credit cost: 1 per successful request
Async: Supported (is_async)
404 billed: No
Plans: Starter, Pro, Ultimate

Authenticate with the x-api-key header. See authentication and credits & billing.

Parameters

Basics

Parameter Description

Parameter	Description
`url` stringrequired	The URL of the webpage to capture. Example: `https://example.com`

url

stringrequired

The URL of the webpage to capture.

Example: https://example.com

AI

Parameter Description

Parameter	Description
`custom_prompt` string	Your own instructions to guide the analysis.
`custom_response` json	Extra fields to return, as a JSON object of {field: description}, e.g. {"sentiment":"overall sentiment"}.
`include_contacts` boolean	Extract emails and phone numbers found on the page. Default: `true`

custom_prompt

string

Your own instructions to guide the analysis.

custom_response

json

Extra fields to return, as a JSON object of {field: description}, e.g. {"sentiment":"overall sentiment"}.

include_contacts

boolean

Extract emails and phone numbers found on the page.

Default: true

Network

Parameter	Description
`proxy` string	Proxy to route the request through.

Cache

Parameter	Description
`cache` boolean	Cache the response at the edge.
`cache_ttl` number	Custom cache TTL in seconds (max 2,592,000 = 30 days, default 86,400).

Global parameters

Accepted by every billable endpoint. Details in Global parameters.

Parameter	Description
`soft_fail` boolean	Return HTTP 200 even when an error occurs, with the message in `error`. Default: `false`
`is_async` boolean	Process asynchronously; returns a `job_id` to poll on /v1/jobs/{id}. Default: `false`
`fields` string	Comma-separated list of response fields to keep (dot notation for nested).
`webhook_url` string	With is_async=true, POST the finished job to this URL (signed, paid plans).

Code examples

curl "http://localhost:4000/v1/analyze?url=https%3A%2F%2Fexample.com" \
  -H "x-api-key: $SCREENSHOTDUDE_API_KEY"

Responses

200 — application/json (custom_response fields are merged into data)

{
  "success": true,
  "data": {
    "summary": "Acme is a project management tool for distributed software teams, combining sprint planning, kanban boards and async standups.",
    "valueProposition": "Ship faster with less coordination overhead for remote teams.",
    "keyFeatures": [
      "Sprint planning",
      "Kanban boards",
      "Async standups",
      "GitHub integration"
    ],
    "categories": [
      "Productivity",
      "Project management",
      "SaaS"
    ],
    "useCases": [
      "Agile sprint tracking",
      "Remote team coordination",
      "Roadmap planning"
    ],
    "targetAudience": "Engineering managers and product teams at remote-first startups",
    "emails": [
      "sales@acme.example"
    ],
    "phoneNumbers": [
      "+1 415 555 0134"
    ],
    "sentiment": "positive"
  }
}

202 — with is_async=true

{
  "success": true,
  "job_id": "job_4f8k2m9q1x7c3v5b6n0z8l2p",
  "status": "Queued"
}

Response fields

Field	Type	Description
`data.summary`	string	A concise summary of the page.
`data.valueProposition`	string	The core promise of the product or page.
`data.keyFeatures`	string[]	Main features or offerings.
`data.categories`	string[]	Industry / topic categories.
`data.useCases`	string[]	Typical use cases.
`data.targetAudience`	string	Who the page is aimed at.
`data.emails`	string[]	Emails found on the page (`include_contacts`).
`data.phoneNumbers`	string[]	Phone numbers found on the page (`include_contacts`).
`data.<custom>`	any	One entry per key of `custom_response`.

Custom fields

custom_response is a JSON object mapping field names to plain-English descriptions:

--data-urlencode 'custom_response={"sentiment":"overall sentiment: positive, neutral or negative","founded_year":"year the company was founded, or null"}'

Each key appears in data next to the standard fields. Describe allowed values to get consistent output.

Prompts and language

custom_prompt adds instructions to the analysis — focus areas, tone or output language ("Answer in French"). It can't change the response structure; use custom_response for that.

Availability

The AI Analysis API is available on paid plans. On the Free plan it returns 403.

Errors

Errors return JSON { "error": "…" }. Failed requests are never billed. Full list in Status codes.

Status	Meaning
400	Missing or invalid parameter (e.g. invalid URL, unsupported format, private network target)
401	Invalid, inactive or expired API key; plan rate limit (`Rate limit exceeded: …`) or key quota (`…: quota daily`)
403	`IP temporarily blocked` after repeated authentication failures; endpoint not included in your plan
402	`Payment required`, `You have open invoices: …` or `Insufficient credits: X required, Y available`
404	Target page not found — not billed
413	Result too large (e.g. extremely tall full-page capture)
500	Rendering failed or timed out (60 s) — not billed; retry or use `is_async=true`