ESO Developer API

ESO's SEO, accessibility, performance and AI-search reports as a JSON API, paid with prepaid credits.

Base URL: http://developer.elitesiteoptimizer.com/api/v1/. Requests and responses are JSON; send Content-Type: application/json with a body. The trailing slash is optional on the Page and Crawl API paths; the account endpoints end with /.

Page API: one URL, one check: POST /page/<check>, or several at once with POST /page/audit. Fast checks answer in the request; slow ones return a job.
Crawl API: a whole website: POST /crawls crawls it and runs reports on every page, then you read pages, issues, broken links, reports, exports and diffs.
Account: balance, plan limits, usage, the credit statement and current prices.

Your first call

Create an account and copy your API keys: a live key (eso_live_…) and a sandbox key (eso_test_…, free sample data).
Pick a plan or buy credits on the pricing page.
Send the request on the right with your key. Try it with the sandbox key first: nothing is charged.

Authentication

Send your key in the Authorization header as Bearer eso_live_YOUR_KEY (X-API-Key also works). A missing, invalid or revoked key, or a suspended account, answers 401 unauthorized.

Key	Prefix	What it does
Live	`eso_live_`	Runs the real reports and uses credits.
Sandbox	`eso_test_`	Realistic sample results for free; never runs an engine. Validation still runs. See Sandbox.

Scopes

A key can be limited to page (Page API and jobs), crawl (Crawl API) and account (account, usage, credit statement). A key with no scopes listed has all of them; a call outside the key's scopes answers 403 scope_denied.

Keep keys on your server, never in a browser or mobile app. Use one key per integration so you can revoke one without stopping the others.

Credits & pricing

Every paid call is priced in credits. Credits are reserved when a request starts and settled when it ends:

A check that succeeds is charged its price; one that fails is refunded in full. An audit is charged the checks that succeed.
A crawl reserves max_pages × (page price + each report's price) and is charged for the pages actually crawled; the rest is released.
Requests refused before they start (validation, blocked or unreachable site) cost nothing. Reading jobs, crawl results and account data is free.

Not enough credits answers 402 insufficient_credits with required and balance. Every response carries X-Credits-Remaining. Current prices are below, on the pricing page and at GET /pricing/.

Check	Credits / URL	Mode
`seo`	2	sync
`site-audit`	3	sync
`schema`	2	sync
`source-code`	3	sync
`accessibility`	5	async
`accessibility-report`	5	async
`links`	3	async
`performance`	10	async
`ai-readiness`	8	async
`readability`	2	sync
`content-optimizer`	25	async
`ai-citation`	15	async
`rank`	5	async
`backlinks`	10	async
`topic-research`	10	async

Crawl	Credits / crawled page
Crawling the page	1
`site_audit` report	1
`broken_links` report	1
`page_index` report	1
`schema` report	1
`source_code` report	1
`readability` report	1
`accessibility` report	3
`performance` report	10

Errors

Errors use the HTTP status and always the same body: {"error": {"code", "message", "request_id", …details}}. Branch on code, not on message. Details depend on the error: param for a bad parameter, required / balance for credits, retry_after for limits, crawler_ips when a site blocks the crawler. Quote request_id (also the X-Request-Id header) to support.

Status	Codes	Meaning
400	`invalid_request` `invalid_json` `invalid_body`	The body is not valid JSON or has the wrong shape.
400	`missing_parameter` `unknown_parameter` `invalid_parameter`	Fix the parameter named in param (see GET /checks).
400	`url_required` `invalid_url` `host_not_found` `invalid_webhook_url`	The url / webhook_url is missing or not a valid public URL.
400	`unknown_check`	No such check (also 404 on POST /page/<check>).
400	`max_pages_exceeded` `invalid_max_pages` `robots_required` `invalid_report`	Crawl settings outside your plan or not valid.
400	`page_unreachable` `site_unreachable` `redirects_off_site` `auth_required`	The page / site could not be loaded (crawl: send http_auth). Not charged.
400	`invalid_cursor` `invalid_date` `invalid_issue_type` `invalid_diff`	A query parameter is not valid.
401	`unauthorized`	Missing, invalid or revoked key, or a suspended account.
402	`insufficient_credits`	Not enough credits; required and balance are included.
403	`scope_denied`	The key lacks the scope of this endpoint.
403	`host_not_public` `domain_not_allowed`	Private address or blocked domain.
404	`not_found` `job_not_found` `crawl_not_found` `report_not_requested` `unknown_report`	No such object for this key's mode (live / test).
409	`crawl_blocked` `auth_required`	The site blocks ESO's crawler or asks for HTTP authentication. Not charged.
409	`crawl_in_progress`	The website is already being crawled: retry when it finishes.
409	`crawl_finished` `crawl_not_finished`	The crawl is not in a state allowing this (cancel / export / diff).
410	`crawl_expired`	The crawl's results were deleted (plan retention).
422	`check_failed` `empty_result`	The check produced no usable data. Refunded.
429	`rate_limited` `daily_limit_reached` `too_many_jobs` `too_many_crawls` `daily_crawl_limit`	A plan limit: wait Retry-After seconds.
500	`internal_error`	A problem on ESO's side: retry, quote request_id.
502	`engine_error`	The report engine failed. Refunded.
503	`job_start_failed` `crawl_start_failed`	The job / crawl could not be queued. Not charged.

Rate limits

Your plan sets the requests per minute and per rolling 24 hours, shared by all keys of the account. Past them the API answers 429 rate_limited (per minute) or 429 daily_limit_reached with a Retry-After header in seconds.

Header	Meaning
`X-RateLimit-Limit`	Requests allowed per minute.
`X-RateLimit-Remaining`	Requests left in the current minute.
`Retry-After`	On 429: seconds to wait before retrying.
`X-Request-Id`	Id of the call.
`X-Credits-Remaining`	Credit balance after the call.

Work running in the background has its own limits: async jobs queued or running at once (429 too_many_jobs), crawls running at once (429 too_many_crawls) and crawls started per 24 hours (429 daily_crawl_limit). One crawl of a website runs at a time across all partners (409 crawl_in_progress). GET /account/ returns your limits.

Idempotency

Send Idempotency-Key: <unique string> (up to 100 characters) on a POST to retry it safely after a timeout or a dropped connection. The same key on the same endpoint within 24 hours returns the first response again, with the header Idempotent-Replayed: true: nothing runs or is charged twice.

Use a value tied to your own operation (an order id, a UUID per task); don't reuse a key for a different request.

Pagination

Lists answer {"object": "list", "data": [...], "has_more", ...}, newest or first rows first. Ask for the next page until has_more is false:

Endpoints	Next page	limit
Crawls and crawl results (pages, issues, links, reports, diff)	`cursor=<next_cursor>` (opaque)	1–500
Jobs	`before=<next_before>` (a job id)	1–100, default 20
Credit transactions	`before=<next_before>` (a transaction id)	1–200, default 50

Webhooks

Give a webhook_url with an async request (or set a default webhook URL in your account) and ESO POSTs the final object when the work ends, so you don't have to poll.

Event	`data`
`job.completed`, `job.failed`	The job, with its result or error.
`crawl.completed`, `crawl.failed`, `crawl.blocked`	The crawl. A partial crawl sends `crawl.completed`.

The body is {"id", "event", "created", "data"}. Answer with a 2xx within 10 seconds; otherwise ESO retries after 30 s and 120 s. Redirects are not followed.

Verify the signature

Each delivery is signed with your webhook secret (shown in your account): ESO-Signature: t=<unix time>,v1=<hex>, where v1 is the HMAC-SHA256 of <t>.<raw body>. Compute it over the raw body before parsing the JSON, compare in constant time and reject old timestamps.

Sandbox

Sandbox keys (eso_test_…) return realistic sample data in the exact shape of live results, for free, so you can build and test an integration without credits:

No engine runs and the target site is never contacted; parameters and URLs are still validated and rate limits apply.
Async checks return a job that is already completed; crawls complete at once on a sample site, and two sandbox crawls of the same site differ a little, to try the diff.
Sandbox and live objects are separate: a sandbox key only sees sandbox jobs and crawls. Responses carry "mode": "test" and credits_charged: 0.

On-page SEO

POST /api/v1/page/seo

On-page SEO: title, meta, headings, canonical, images, links

Credits 2 credits per URL Sync Sync: 200 with the result ("wait": false returns a job)

Request body (JSON)

Field name	Type	Description
`url`required	string	Page to check (http/https; the scheme defaults to https). Max length: 2000
`webhook_url`optional	string	URL notified when the job ends (job.completed / job.failed); default: the account's webhook URL. Max length: 500
`wait`optional	boolean	Sync checks: false returns a job at once instead of waiting for the result. Async checks always return a job. Default: `true` Max length: 200

Response fields

Field name	Type	Description
`id`	string	Unique id of the object.
`object`	string	Always page_check.
`check`	string	Check slug.
`url`	string	URL the request was made for.
`mode`	string	live (real run, credits) or test (sandbox key, sample data, free).
`credits_charged`	integer	Credits charged: 0 when it failed (refunded) and for sandbox keys.
`created_at`	string	When it was created (ISO 8601, UTC).
`result`	object	The check's result; its fields are listed below.
`result.page_url`	string	The page checked.
`result.canonical_url`	string	Canonical URL declared by the page.
`result.meta_description`	string	Meta description text.
`result.h1_count`	integer	Number of H1 headings.
`result.h1_tags`	array	Text of each H1.
`result.images`	array	Images of the page: img_url, alt.
`result.missing_alt_count`	integer	Images without alt text.
`result.missing_alt_images`	array	URLs of the images without alt text.
`result.pagination`	object	rel=prev / rel=next URLs.
`result.hreflang`	array	hreflang alternates of the page.
`result.checks`	object	true / false of each on-page test: missing title, description, canonical, H1, duplicates, noindex …
`result.issues`	array	The failed checks, as a list.

Errors

400invalid_request400missing_parameter400unknown_parameter400invalid_url402insufficient_credits409crawl_blocked400auth_required400page_unreachable422check_failed422empty_result502engine_error401unauthorized403scope_denied429rate_limited

Site audit

POST /api/v1/page/site-audit

Site audit issues of the page

Credits 3 credits per URL Sync Sync: 200 with the result ("wait": false returns a job)

Request body (JSON)

Field name	Type	Description
`url`required	string	Page to check (http/https; the scheme defaults to https). Max length: 2000
`webhook_url`optional	string	URL notified when the job ends (job.completed / job.failed); default: the account's webhook URL. Max length: 500
`wait`optional	boolean	Sync checks: false returns a job at once instead of waiting for the result. Async checks always return a job. Default: `true` Max length: 200

Response fields

Field name	Type	Description
`id`	string	Unique id of the object.
`object`	string	Always page_check.
`check`	string	Check slug.
`url`	string	URL the request was made for.
`mode`	string	live (real run, credits) or test (sandbox key, sample data, free).
`credits_charged`	integer	Credits charged: 0 when it failed (refunded) and for sandbox keys.
`created_at`	string	When it was created (ISO 8601, UTC).
`result`	object	The check's result; its fields are listed below.
`result.health_score`	integer	Site audit health score, 0 to 100.
`result.total_issues`	integer	Number of issues found.
`result.by_priority`	object	Issues per priority: high, medium, low.
`result.issues`	array	Each issue: issue, label, priority, count.
`result.site_metrics`	object	Page counters used by the audit.

Errors

400invalid_request400missing_parameter400unknown_parameter400invalid_url402insufficient_credits409crawl_blocked400auth_required400page_unreachable422check_failed422empty_result502engine_error401unauthorized403scope_denied429rate_limited

Schema

POST /api/v1/page/schema

Structured data found, errors and missing properties

Credits 2 credits per URL Sync Sync: 200 with the result ("wait": false returns a job)

Request body (JSON)

Field name	Type	Description
`url`required	string	Page to check (http/https; the scheme defaults to https). Max length: 2000
`webhook_url`optional	string	URL notified when the job ends (job.completed / job.failed); default: the account's webhook URL. Max length: 500
`wait`optional	boolean	Sync checks: false returns a job at once instead of waiting for the result. Async checks always return a job. Default: `true` Max length: 200

Response fields

Field name	Type	Description
`id`	string	Unique id of the object.
`object`	string	Always page_check.
`check`	string	Check slug.
`url`	string	URL the request was made for.
`mode`	string	live (real run, credits) or test (sandbox key, sample data, free).
`credits_charged`	integer	Credits charged: 0 when it failed (refunded) and for sandbox keys.
`created_at`	string	When it was created (ISO 8601, UTC).
`result`	object	The check's result; its fields are listed below.
`result.error_count`	integer	Structured data errors (missing required properties).
`result.warning_count`	integer	Warnings (missing recommended properties).
`result.items`	array	Each structured data item: type, missing_required, missing_recommended, properties.

Errors

400invalid_request400missing_parameter400unknown_parameter400invalid_url402insufficient_credits409crawl_blocked400auth_required400page_unreachable422check_failed422empty_result502engine_error401unauthorized403scope_denied429rate_limited

Source code

POST /api/v1/page/source-code

HTML validation errors and warnings

Credits 3 credits per URL Sync Sync: 200 with the result ("wait": false returns a job)

Request body (JSON)

Field name	Type	Description
`url`required	string	Page to check (http/https; the scheme defaults to https). Max length: 2000
`webhook_url`optional	string	URL notified when the job ends (job.completed / job.failed); default: the account's webhook URL. Max length: 500
`wait`optional	boolean	Sync checks: false returns a job at once instead of waiting for the result. Async checks always return a job. Default: `true` Max length: 200

Response fields

Field name	Type	Description
`id`	string	Unique id of the object.
`object`	string	Always page_check.
`check`	string	Check slug.
`url`	string	URL the request was made for.
`mode`	string	live (real run, credits) or test (sandbox key, sample data, free).
`credits_charged`	integer	Credits charged: 0 when it failed (refunded) and for sandbox keys.
`created_at`	string	When it was created (ISO 8601, UTC).
`result`	object	The check's result; its fields are listed below.
`result.errors`	integer	HTML validation errors.
`result.warnings`	integer	Validation warnings.
`result.fatal_errors`	integer	Fatal errors (the document could not be parsed).
`result.infos`	integer	Informational messages.
`result.issues`	array	Each message: type, message, location, snippet.

Errors

400invalid_request400missing_parameter400unknown_parameter400invalid_url402insufficient_credits409crawl_blocked400auth_required400page_unreachable422check_failed422empty_result502engine_error401unauthorized403scope_denied429rate_limited

Accessibility score

POST /api/v1/page/accessibility

Accessibility score and WCAG issues (axe)

Credits 5 credits per URL Async Async: 202 with a job, result by webhook or GET /jobs/<id>

Request body (JSON)

Field name	Type	Description
`url`required	string	Page to check (http/https; the scheme defaults to https). Max length: 2000
`audit_type`optional	string	Which axe rules to list: the failed ones or the passed ones. Default: `"failed"` Allowed: `failed`, `passed`
`webhook_url`optional	string	URL notified when the job ends (job.completed / job.failed); default: the account's webhook URL. Max length: 500
`wait`optional	boolean	Sync checks: false returns a job at once instead of waiting for the result. Async checks always return a job. Default: `true` Max length: 200

Response fields

Async checks answer with a job; this page_check object is the job's result once it completes.

Field name	Type	Description
`id`	string	Unique id of the object.
`object`	string	Always page_check.
`check`	string	Check slug.
`url`	string	URL the request was made for.
`mode`	string	live (real run, credits) or test (sandbox key, sample data, free).
`credits_charged`	integer	Credits charged: 0 when it failed (refunded) and for sandbox keys.
`created_at`	string	When it was created (ISO 8601, UTC).
`result`	object	The check's result; its fields are listed below.
`result.score`	integer	Accessibility score (axe), 0 to 100.
`result.passed_rules`	integer	axe rules passed.
`result.failed_rules`	integer	axe rules failed.
`result.audit_type`	string	failed or passed: which rules are listed.
`result.rules`	array	Each rule: rule, impact, description, help, count, elements (html, message).

Errors

400invalid_request400missing_parameter400unknown_parameter400invalid_url402insufficient_credits409crawl_blocked400auth_required400page_unreachable422check_failed422empty_result502engine_error429too_many_jobs503job_start_failed401unauthorized403scope_denied429rate_limited

Accessibility report

POST /api/v1/page/accessibility-report

Accessibility report by section

Credits 5 credits per URL Async Async: 202 with a job, result by webhook or GET /jobs/<id>

Request body (JSON)

Field name	Type	Description
`url`required	string	Page to check (http/https; the scheme defaults to https). Max length: 2000
`webhook_url`optional	string	URL notified when the job ends (job.completed / job.failed); default: the account's webhook URL. Max length: 500
`wait`optional	boolean	Sync checks: false returns a job at once instead of waiting for the result. Async checks always return a job. Default: `true` Max length: 200

Response fields

Async checks answer with a job; this page_check object is the job's result once it completes.

Field name	Type	Description
`id`	string	Unique id of the object.
`object`	string	Always page_check.
`check`	string	Check slug.
`url`	string	URL the request was made for.
`mode`	string	live (real run, credits) or test (sandbox key, sample data, free).
`credits_charged`	integer	Credits charged: 0 when it failed (refunded) and for sandbox keys.
`created_at`	string	When it was created (ISO 8601, UTC).
`result`	object	The check's result; its fields are listed below.
`result.score`	integer	Accessibility score, 0 to 100.
`result.summary`	object	Rules passed, failed, with warnings and not applicable.
`result.sections`	array	Rules by section: title, requirement, status, element counts and failed examples.

Errors

400invalid_request400missing_parameter400unknown_parameter400invalid_url402insufficient_credits409crawl_blocked400auth_required400page_unreachable422check_failed422empty_result502engine_error429too_many_jobs503job_start_failed401unauthorized403scope_denied429rate_limited

Links

POST /api/v1/page/links

Broken internal and external links on the page

Credits 3 credits per URL Async Async: 202 with a job, result by webhook or GET /jobs/<id>

Request body (JSON)

Field name	Type	Description
`url`required	string	Page to check (http/https; the scheme defaults to https). Max length: 2000
`include_links`optional	boolean	Return every link with its status code (false: counts only). Default: `true` Max length: 200
`webhook_url`optional	string	URL notified when the job ends (job.completed / job.failed); default: the account's webhook URL. Max length: 500
`wait`optional	boolean	Sync checks: false returns a job at once instead of waiting for the result. Async checks always return a job. Default: `true` Max length: 200

Response fields

Async checks answer with a job; this page_check object is the job's result once it completes.

Field name	Type	Description
`id`	string	Unique id of the object.
`object`	string	Always page_check.
`check`	string	Check slug.
`url`	string	URL the request was made for.
`mode`	string	live (real run, credits) or test (sandbox key, sample data, free).
`credits_charged`	integer	Credits charged: 0 when it failed (refunded) and for sandbox keys.
`created_at`	string	When it was created (ISO 8601, UTC).
`result`	object	The check's result; its fields are listed below.
`result.status_code`	integer	HTTP status of the page itself.
`result.valid`	boolean	The page loaded.
`result.broken_links`	integer	Broken links found (4xx / 5xx).
`result.internal`	object	Internal links: totals, health_score and links (url, status_code, anchor_text, content_type).
`result.external`	object	External links, same fields as internal.

Errors

400invalid_request400missing_parameter400unknown_parameter400invalid_url402insufficient_credits409crawl_blocked400auth_required400page_unreachable422check_failed422empty_result502engine_error429too_many_jobs503job_start_failed401unauthorized403scope_denied429rate_limited

Performance

POST /api/v1/page/performance

Lighthouse performance and Core Web Vitals

Credits 10 credits per URL Async Async: 202 with a job, result by webhook or GET /jobs/<id>

Request body (JSON)

Field name	Type	Description
`url`required	string	Page to check (http/https; the scheme defaults to https). Max length: 2000
`webhook_url`optional	string	URL notified when the job ends (job.completed / job.failed); default: the account's webhook URL. Max length: 500
`wait`optional	boolean	Sync checks: false returns a job at once instead of waiting for the result. Async checks always return a job. Default: `true` Max length: 200

Response fields

Async checks answer with a job; this page_check object is the job's result once it completes.

Field name	Type	Description
`id`	string	Unique id of the object.
`object`	string	Always page_check.
`check`	string	Check slug.
`url`	string	URL the request was made for.
`mode`	string	live (real run, credits) or test (sandbox key, sample data, free).
`credits_charged`	integer	Credits charged: 0 when it failed (refunded) and for sandbox keys.
`created_at`	string	When it was created (ISO 8601, UTC).
`result`	object	The check's result; its fields are listed below.
`result.score`	integer	Lighthouse performance score, 0 to 100.
`result.summary`	object	Metrics per status: good, needs_improvement, poor, info.
`result.metrics`	array	Each metric (LCP, FCP, TBT, CLS, TTFB …): metric, title, status, value, message.

Errors

400invalid_request400missing_parameter400unknown_parameter400invalid_url402insufficient_credits409crawl_blocked400auth_required400page_unreachable422check_failed422empty_result502engine_error429too_many_jobs503job_start_failed401unauthorized403scope_denied429rate_limited

AI readiness

POST /api/v1/page/ai-readiness

AI readiness score by section

Credits 8 credits per URL Async Async: 202 with a job, result by webhook or GET /jobs/<id>

Request body (JSON)

Field name	Type	Description
`url`required	string	Page to check (http/https; the scheme defaults to https). Max length: 2000
`webhook_url`optional	string	URL notified when the job ends (job.completed / job.failed); default: the account's webhook URL. Max length: 500
`wait`optional	boolean	Sync checks: false returns a job at once instead of waiting for the result. Async checks always return a job. Default: `true` Max length: 200

Response fields

Async checks answer with a job; this page_check object is the job's result once it completes.

Field name	Type	Description
`id`	string	Unique id of the object.
`object`	string	Always page_check.
`check`	string	Check slug.
`url`	string	URL the request was made for.
`mode`	string	live (real run, credits) or test (sandbox key, sample data, free).
`credits_charged`	integer	Credits charged: 0 when it failed (refunded) and for sandbox keys.
`created_at`	string	When it was created (ISO 8601, UTC).
`result`	object	The check's result; its fields are listed below.
`result.score`	integer	AI readiness score, 0 to 100.
`result.sections`	object	crawlability, semantic_structure, content_quality, structured_data, user_experience, authority_context: status and checks.

Errors

400invalid_request400missing_parameter400unknown_parameter400invalid_url402insufficient_credits409crawl_blocked400auth_required400page_unreachable422check_failed422empty_result502engine_error429too_many_jobs503job_start_failed401unauthorized403scope_denied429rate_limited

Readability

POST /api/v1/page/readability

Readability analysis

Credits 2 credits per URL Sync Sync: 200 with the result ("wait": false returns a job)

Request body (JSON)

Field name	Type	Description
`url`required	string	Page to check (http/https; the scheme defaults to https). Max length: 2000
`webhook_url`optional	string	URL notified when the job ends (job.completed / job.failed); default: the account's webhook URL. Max length: 500
`wait`optional	boolean	Sync checks: false returns a job at once instead of waiting for the result. Async checks always return a job. Default: `true` Max length: 200

Response fields

Field name	Type	Description
`id`	string	Unique id of the object.
`object`	string	Always page_check.
`check`	string	Check slug.
`url`	string	URL the request was made for.
`mode`	string	live (real run, credits) or test (sandbox key, sample data, free).
`credits_charged`	integer	Credits charged: 0 when it failed (refunded) and for sandbox keys.
`created_at`	string	When it was created (ISO 8601, UTC).
`result`	object	The check's result; its fields are listed below.
`result.score`	integer	Readability score, 0 to 100.
`result.summary`	object	Number of audits passed, okay and failed.
`result.audits`	array	Each audit: check, label, status, value, detail.

Errors

400invalid_request400missing_parameter400unknown_parameter400invalid_url402insufficient_credits409crawl_blocked400auth_required400page_unreachable422check_failed422empty_result502engine_error401unauthorized403scope_denied429rate_limited

AI content optimizer

POST /api/v1/page/content-optimizer

AI Content Optimizer: readability, keywords, tone, AI rewrites

Credits 25 credits per URL Async Async: 202 with a job, result by webhook or GET /jobs/<id>

Request body (JSON)

Field name	Type	Description
`url`required	string	Page to check (http/https; the scheme defaults to https). Max length: 2000
`location`optional	string	Country / region name for search data, e.g. "United States", "United Kingdom". Default: `"United States"` Max length: 100
`ai_suggestions`optional	boolean	Generate AI rewrites of low-readability elements. Default: `true` Max length: 200
`webhook_url`optional	string	URL notified when the job ends (job.completed / job.failed); default: the account's webhook URL. Max length: 500
`wait`optional	boolean	Sync checks: false returns a job at once instead of waiting for the result. Async checks always return a job. Default: `true` Max length: 200

Response fields

Async checks answer with a job; this page_check object is the job's result once it completes.

Field name	Type	Description
`id`	string	Unique id of the object.
`object`	string	Always page_check.
`check`	string	Check slug.
`url`	string	URL the request was made for.
`mode`	string	live (real run, credits) or test (sandbox key, sample data, free).
`credits_charged`	integer	Credits charged: 0 when it failed (refunded) and for sandbox keys.
`created_at`	string	When it was created (ISO 8601, UTC).
`result`	object	The check's result; its fields are listed below.
`result.overall`	object	Readability, AI readability and tone scores with their status.
`result.readability`	object	Readability of each element, with an AI rewrite (ai_suggestion) of the hard ones.
`result.keywords`	object	Keywords found and new keyword suggestions with search volume.
`result.tone`	object	Tone of each element and the overall tone score.
`result.quality_matrix`	array	Readability and tone of each element side by side.

Errors

400invalid_request400missing_parameter400unknown_parameter400invalid_url402insufficient_credits409crawl_blocked400auth_required400page_unreachable422check_failed422empty_result502engine_error429too_many_jobs503job_start_failed401unauthorized403scope_denied429rate_limited

AI citation

POST /api/v1/page/ai-citation

AI citation check across AI assistants

Credits 15 credits per URL Async Async: 202 with a job, result by webhook or GET /jobs/<id>

Request body (JSON)

Field name	Type	Description
`url`required	string	Page to check (http/https; the scheme defaults to https). Max length: 2000
`query`required	string	The question asked to the AI assistants, e.g. "best project management tool". Max length: 500
`brand_name`optional	string	Brand to look for in the answers (default: from the domain name). Max length: 100
`webhook_url`optional	string	URL notified when the job ends (job.completed / job.failed); default: the account's webhook URL. Max length: 500
`wait`optional	boolean	Sync checks: false returns a job at once instead of waiting for the result. Async checks always return a job. Default: `true` Max length: 200

Response fields

Async checks answer with a job; this page_check object is the job's result once it completes.

Field name	Type	Description
`id`	string	Unique id of the object.
`object`	string	Always page_check.
`check`	string	Check slug.
`url`	string	URL the request was made for.
`mode`	string	live (real run, credits) or test (sandbox key, sample data, free).
`credits_charged`	integer	Credits charged: 0 when it failed (refunded) and for sandbox keys.
`created_at`	string	When it was created (ISO 8601, UTC).
`result`	object	The check's result; its fields are listed below.
`result.query`	string	The question asked.
`result.brand_name`	string	Brand looked for.
`result.citation_rate`	integer	Share of the assistants citing the site, in %.
`result.cited_by`	array	Assistants that cite the site.
`result.mentioned_by`	array	Assistants that mention the brand.
`result.answers`	array	Each assistant's answer: cited, rank_position, cited_urls, mentions, sentiment, competitors.

Errors

400invalid_request400missing_parameter400unknown_parameter400invalid_url402insufficient_credits422check_failed422empty_result502engine_error429too_many_jobs503job_start_failed401unauthorized403scope_denied429rate_limited

Rank checker

POST /api/v1/page/rank

Google ranking of keywords for the URL

Credits 5 credits per URL Async Async: 202 with a job, result by webhook or GET /jobs/<id>

Request body (JSON)

Field name	Type	Description
`url`required	string	Page to check (http/https; the scheme defaults to https). Max length: 2000
`keyword`required	string	Keyword to search. Max length: 200
`search_engine`optional	string	Search engine. Default: `"google"` Allowed: `google`, `bing`
`location`optional	string	Country / region name for search data, e.g. "United States", "United Kingdom". Default: `"United States"` Max length: 100
`state`optional	string	State / region inside the location (optional). Max length: 100
`city`optional	string	City inside the location (optional). Max length: 100
`device`optional	string	Device of the search. Default: `"desktop"` Allowed: `desktop`, `mobile`, `ios`, `android`
`webhook_url`optional	string	URL notified when the job ends (job.completed / job.failed); default: the account's webhook URL. Max length: 500
`wait`optional	boolean	Sync checks: false returns a job at once instead of waiting for the result. Async checks always return a job. Default: `true` Max length: 200

Response fields

Async checks answer with a job; this page_check object is the job's result once it completes.

Field name	Type	Description
`id`	string	Unique id of the object.
`object`	string	Always page_check.
`check`	string	Check slug.
`url`	string	URL the request was made for.
`mode`	string	live (real run, credits) or test (sandbox key, sample data, free).
`credits_charged`	integer	Credits charged: 0 when it failed (refunded) and for sandbox keys.
`created_at`	string	When it was created (ISO 8601, UTC).
`result`	object	The check's result; its fields are listed below.
`result.keyword`	string	Keyword searched.
`result.search_engine`	string	google or bing.
`result.location`	string	Country / region of the search.
`result.state`	string \| null	State / region, when given.
`result.city`	string \| null	City, when given.
`result.device`	string	Device of the search.
`result.ranked`	boolean	The URL is in the results checked.
`result.position`	integer \| null	Position of the URL, null when not ranked.
`result.ranking_url`	string	The URL looked for.
`result.results_checked`	integer	Number of results checked.
`result.search_volume`	object	Average monthly searches and competition of the keyword.

Errors

400invalid_request400missing_parameter400unknown_parameter400invalid_url402insufficient_credits422check_failed422empty_result502engine_error429too_many_jobs503job_start_failed401unauthorized403scope_denied429rate_limited

Backlinks

POST /api/v1/page/backlinks

Backlink research of the domain

Credits 10 credits per URL Async Async: 202 with a job, result by webhook or GET /jobs/<id>

Request body (JSON)

Field name	Type	Description
`url`required	string	Page to check (http/https; the scheme defaults to https). Max length: 2000
`limit`optional	integer	Backlinks to return (strongest first). Default: `100` Range: 1 to 1000
`webhook_url`optional	string	URL notified when the job ends (job.completed / job.failed); default: the account's webhook URL. Max length: 500
`wait`optional	boolean	Sync checks: false returns a job at once instead of waiting for the result. Async checks always return a job. Default: `true` Max length: 200

Response fields

Async checks answer with a job; this page_check object is the job's result once it completes.

Field name	Type	Description
`id`	string	Unique id of the object.
`object`	string	Always page_check.
`check`	string	Check slug.
`url`	string	URL the request was made for.
`mode`	string	live (real run, credits) or test (sandbox key, sample data, free).
`credits_charged`	integer	Credits charged: 0 when it failed (refunded) and for sandbox keys.
`created_at`	string	When it was created (ISO 8601, UTC).
`result`	object	The check's result; its fields are listed below.
`result.target`	string	Domain researched.
`result.mode`	string	domain
`result.summary`	object	Domain rank, backlinks (dofollow / nofollow / broken), referring domains and IPs, first seen.
`result.backlinks`	array	Strongest backlinks first: source_url, source_title, ranks, target_url, anchor, dofollow, dates.

Errors

400invalid_request400missing_parameter400unknown_parameter400invalid_url402insufficient_credits422check_failed422empty_result502engine_error429too_many_jobs503job_start_failed401unauthorized403scope_denied429rate_limited

Topic research

POST /api/v1/page/topic-research

Topic research for a keyword

Credits 10 credits per URL Async Async: 202 with a job, result by webhook or GET /jobs/<id>

Request body (JSON)

Field name	Type	Description
`url`optional	string	Page to check (http/https; the scheme defaults to https). Max length: 2000
`keyword`required	string	Root keyword to research. Max length: 200
`location`optional	string	Country / region name for search data, e.g. "United States", "United Kingdom". Default: `"United States"` Max length: 100
`webhook_url`optional	string	URL notified when the job ends (job.completed / job.failed); default: the account's webhook URL. Max length: 500
`wait`optional	boolean	Sync checks: false returns a job at once instead of waiting for the result. Async checks always return a job. Default: `true` Max length: 200

Response fields

Async checks answer with a job; this page_check object is the job's result once it completes.

Field name	Type	Description
`id`	string	Unique id of the object.
`object`	string	Always page_check.
`check`	string	Check slug.
`url`	string	URL the request was made for.
`mode`	string	live (real run, credits) or test (sandbox key, sample data, free).
`credits_charged`	integer	Credits charged: 0 when it failed (refunded) and for sandbox keys.
`created_at`	string	When it was created (ISO 8601, UTC).
`result`	object	The check's result; its fields are listed below.
`result.keyword`	string	Root keyword.
`result.location`	string	Country / region of the search data.
`result.serp_urls`	array	Top-ranking pages analyzed.
`result.pages_analyzed`	integer	Number of pages analyzed.
`result.competitors`	object	Keywords, topics and questions found on the competing pages.
`result.ai_strategy`	object	AI content strategy: intent, opportunity keywords, topic clusters, content ideas, questions.

Errors

400invalid_request400missing_parameter400unknown_parameter400invalid_url402insufficient_credits422check_failed422empty_result502engine_error429too_many_jobs503job_start_failed401unauthorized403scope_denied429rate_limited

Audit: several checks

POST /api/v1/page/audit

Several checks of one URL in one call. Results come back together, keyed by check.

Credits Sum of the checks' credits; checks that fail are refunded Sync or async Sync when every check is sync; a job (202) when any check is async or "wait": false

Request body (JSON)

Field name	Type	Description
`url`required	string	Page to check (http/https; the scheme defaults to https). Max length: 2000
`checks`required	array	Check slugs to run, each once. Allowed: `seo`, `site-audit`, `schema`, `source-code`, `accessibility`, `accessibility-report`, `links`, `performance`, `ai-readiness`, `readability`, `content-optimizer`, `ai-citation`, `rank`, `backlinks`, `topic-research` Max items: 15
`options`optional	object	Parameters per check: {"<check>": {params}}, e.g. {"rank": {"keyword": "trail running shoes"}}. Only for checks listed in checks.
`webhook_url`optional	string	URL notified when the job ends (job.completed / job.failed). Max length: 500
`wait`optional	boolean	false returns a job at once even when every check is sync. Default: `true`

Response fields

As a job, the page_audit object is the job's result once it completes.

Field name	Type	Description
`id`	string	Unique id of the object.
`object`	string	Always page_audit.
`url`	string	URL the request was made for.
`checks`	array	The checks run, in order.
`mode`	string	live (real run, credits) or test (sandbox key, sample data, free).
`credits_charged`	integer	Sum of the credits of the checks that succeeded.
`created_at`	string	When it was created (ISO 8601, UTC).
`results`	object	{"<check>": result} of each check that succeeded.
`errors`	object	{"<check>": {code, message}} of each check that failed (refunded).

Errors

400invalid_request400unknown_check400unknown_parameter402insufficient_credits409crawl_blocked400page_unreachable422check_failed429too_many_jobs401unauthorized403scope_denied429rate_limited

Get a job

GET /api/v1/jobs/{job_id}

Status of an async check or audit, with its result once completed (until the plan's result retention ends). Poll every few seconds, or use a webhook.

Credits Free Sync answered in the request

Path parameters

Field name	Type	Description
`job_id`required	string	Id of the job (job_…).

Response fields

Field name	Type	Description
`id`	string	Unique id of the object.
`object`	string	Always job.
`check`	string	Check slug, or audit.
`url`	string	URL the request was made for.
`params`	object	The check parameters, as validated, with their defaults.
`status`	string	queued, running, completed or failed.
`mode`	string	live (real run, credits) or test (sandbox key, sample data, free).
`credits_reserved`	integer	Credits held when it started; the unused part is released when it ends.
`credits_charged`	integer	Credits charged: 0 when it failed (refunded) and for sandbox keys.
`created_at`	string	When it was created (ISO 8601, UTC).
`started_at`	string \| null	When the work started.
`completed_at`	string \| null	When it ended.
`expires_at`	string \| null	When the result is deleted (plan's result retention).
`result`	object	Once completed: the page_check (or page_audit) object, until the result expires.
`result_expired`	boolean	Once completed: true when the result was deleted after the retention period.

Errors

404job_not_found401unauthorized403scope_denied429rate_limited

List jobs

GET /api/v1/jobs

The jobs of the key's mode (live or sandbox), newest first.

Credits Free Sync answered in the request

Query parameters

Field name	Type	Description
`status`optional	string	Only jobs in this status. Allowed: `queued`, `running`, `completed`, `failed`
`check`optional	string	Only jobs of this check (or audit). Allowed: `seo`, `site-audit`, `schema`, `source-code`, `accessibility`, `accessibility-report`, `links`, `performance`, `ai-readiness`, `readability`, `content-optimizer`, `ai-citation`, `rank`, `backlinks`, `topic-research`, `audit`
`limit`optional	integer	Jobs per page. Default: `20` Range: 1 to 100
`before`optional	string	next_before of the previous page (a job id).

Response fields

Field name	Type	Description
`object`	string	Always list.
`data`	array	Job objects, newest first.
`has_more`	boolean	true when another page follows.
`next_before`	string	Pass it as before to get the next page; null on the last page.

Errors

400invalid_request400unknown_check400invalid_cursor401unauthorized403scope_denied429rate_limited

Checks catalog

GET /api/v1/checks

Every check with its description, current credits, sync / async mode and parameters, plus the audit entry. Build forms or validate requests from it. The sample shows two entries.

Credits Free Sync answered in the request

Request parameters

None.

Response fields

Field name	Type	Description
`object`	string	Always list.
`data`	array	One entry per check: check, description, credits, mode, endpoint, fetches_page, params (name, type, required, description, default, enum, limits); plus the audit entry.
`data[].check`	string	Check slug.
`data[].description`	string
`data[].credits`	integer	balance: credits available now.
`data[].mode`	string	live (real run, credits) or test (sandbox key, sample data, free).
`data[].endpoint`	string
`data[].fetches_page`	boolean
`data[].params`	array	The check parameters, as validated, with their defaults.

Errors

401unauthorized429rate_limited

Start a crawl

POST /api/v1/crawls

Crawls a whole website and runs the chosen reports on every page. Always asynchronous: poll GET /crawls/{crawl_id} or wait for the crawl.completed webhook. Only one crawl of a website runs at a time (across all partners).

Credits Reserves max_pages × (1 per page + each report's price per page: site_audit 1, broken_links 1, page_index 1, schema 1, source_code 1, readability 1, accessibility 3, performance 10); charged for the pages actually crawled, the rest released Async Async: 202 with the crawl (queued); sandbox crawls complete at once

Request body (JSON)

Field name	Type	Description
`url`required	string	Start page of the website (http/https). Max length: 255
`max_pages`required	integer	Pages to crawl at most; up to your plan's max_pages_per_crawl. Minimum: 1
`max_depth`optional	integer	Clicks from the start page (1 = its links). Default: no limit. Range: 1 to 100
`reports`optional	array	Reports to run on the crawled pages. Default: `[]` Allowed: `site_audit`, `broken_links`, `page_index`, `schema`, `source_code`, `readability`, `accessibility`, `performance`
`respect_robots`optional	boolean	Follow robots.txt. false only on plans allowing it (else robots_required). Default: `true`
`include_subdomains`optional	boolean	Also crawl subdomains of the host. Default: `false`
`include_patterns`optional	array	Only crawl paths matching these patterns, e.g. ["/blog/*"]. Max items: 20 Max length: 200
`exclude_patterns`optional	array	Skip paths matching these patterns, e.g. ["?sort="]. Max items: 20 Max length: 200
`js_rendering`optional	boolean	Render pages with a browser (JavaScript sites). Default: `false`
`http_auth`optional	object	{"username", "password"} of a site behind HTTP authentication (staging). Dropped when the crawl ends.
`webhook_url`optional	string	URL notified when the crawl ends (crawl.completed / crawl.failed / crawl.blocked); default: the account's webhook URL.

Response fields

Field name	Type	Description
`id`	string	Unique id of the object.
`object`	string	Always crawl.
`mode`	string	live (real run, credits) or test (sandbox key, sample data, free).
`url`	string	Start URL of the crawl (after redirects within the site).
`host`	string	Website crawled (without www.).
`status`	string	queued, crawling, analyzing, then completed, partial, failed, blocked or cancelled.
`settings`	object	The crawl settings as validated (http_auth: true when credentials were given).
`progress`	object	pages_found, pages_crawled, max_pages and crawl_percent.
`credits_reserved`	integer	max_pages × (page price + each report's price), held at the start.
`credits_charged`	integer	Final charge: pages crawled × (page price + completed reports); set when it ends.
`error`	object \| null	{code, message} when it failed, else null.
`previous_crawl_id`	string \| null	The previous crawl of the same site, to diff against.
`webhook_url`	string \| null	URL notified when the crawl ends.
`created_at`	string	When it was created (ISO 8601, UTC).
`started_at`	string \| null	When the work started.
`completed_at`	string \| null	When it ended.
`expires_at`	string \| null	When the result is deleted (plan's result retention).
`data_expired`	boolean	true once the results were deleted (plan retention): result endpoints answer 410.
`reports`	array	Each report: {name, status (queued, running, completed, failed, skipped), url}.
`links`	object	URLs of the result endpoints of this crawl.

Errors

400invalid_request400invalid_max_pages400max_pages_exceeded400invalid_report400robots_required400invalid_url400site_unreachable400auth_required400redirects_off_site409crawl_blocked409crawl_in_progress402insufficient_credits429too_many_crawls429daily_crawl_limit503crawl_start_failed401unauthorized403scope_denied429rate_limited

List crawls

GET /api/v1/crawls

The crawls of the key's mode (live or sandbox), newest first.

Credits Free Sync answered in the request

Query parameters

Field name	Type	Description
`status`optional	string	Only crawls in this status. Allowed: `queued`, `crawling`, `analyzing`, `completed`, `partial`, `failed`, `blocked`, `cancelled`
`host`optional	string	Only crawls of this website (without www.).
`limit`optional	integer	Crawls per page. Default: `50` Range: 1 to 500
`cursor`optional	string	next_cursor of the previous page.

Response fields

Field name	Type	Description
`object`	string	Always list.
`data`	array	Crawl objects, newest first (reports as a list of names).
`has_more`	boolean	true when another page follows.
`next_cursor`	string \| null	Pass it as cursor to get the next page; null on the last page.

Errors

400invalid_request400invalid_cursor401unauthorized403scope_denied429rate_limited

Get a crawl

GET /api/v1/crawls/{crawl_id}

Status, progress and the status of each report, with links to the result endpoints.

Credits Free Sync answered in the request

Path parameters

Field name	Type	Description
`crawl_id`required	string	Id of the crawl (crl_…).

Response fields

Field name	Type	Description
`id`	string	Unique id of the object.
`object`	string	Always crawl.
`mode`	string	live (real run, credits) or test (sandbox key, sample data, free).
`url`	string	Start URL of the crawl (after redirects within the site).
`host`	string	Website crawled (without www.).
`status`	string	queued, crawling, analyzing, then completed, partial, failed, blocked or cancelled.
`settings`	object	The crawl settings as validated (http_auth: true when credentials were given).
`progress`	object	pages_found, pages_crawled, max_pages and crawl_percent.
`credits_reserved`	integer	max_pages × (page price + each report's price), held at the start.
`credits_charged`	integer	Final charge: pages crawled × (page price + completed reports); set when it ends.
`error`	object \| null	{code, message} when it failed, else null.
`previous_crawl_id`	string \| null	The previous crawl of the same site, to diff against.
`webhook_url`	string \| null	URL notified when the crawl ends.
`created_at`	string	When it was created (ISO 8601, UTC).
`started_at`	string \| null	When the work started.
`completed_at`	string \| null	When it ended.
`expires_at`	string \| null	When the result is deleted (plan's result retention).
`data_expired`	boolean	true once the results were deleted (plan retention): result endpoints answer 410.
`reports`	array	Each report: {name, status (queued, running, completed, failed, skipped), url}.
`links`	object	URLs of the result endpoints of this crawl.

Errors

404crawl_not_found401unauthorized403scope_denied429rate_limited

Cancel a crawl

DELETE /api/v1/crawls/{crawl_id}

Stops a running crawl. The pages crawled so far (and the reports that finished) are charged; the rest of the reservation is released. Sandbox crawls are already complete.

Credits Free; unused credits refunded Sync answered in the request

Path parameters

Field name	Type	Description
`crawl_id`required	string	Id of the crawl (crl_…).

Response fields

Field name	Type	Description
`id`	string	Unique id of the object.
`object`	string	Always crawl.
`mode`	string	live (real run, credits) or test (sandbox key, sample data, free).
`url`	string	Start URL of the crawl (after redirects within the site).
`host`	string	Website crawled (without www.).
`status`	string	queued, crawling, analyzing, then completed, partial, failed, blocked or cancelled.
`settings`	object	The crawl settings as validated (http_auth: true when credentials were given).
`progress`	object	pages_found, pages_crawled, max_pages and crawl_percent.
`credits_reserved`	integer	max_pages × (page price + each report's price), held at the start.
`credits_charged`	integer	Final charge: pages crawled × (page price + completed reports); set when it ends.
`error`	object \| null	{code, message} when it failed, else null.
`previous_crawl_id`	string \| null	The previous crawl of the same site, to diff against.
`webhook_url`	string \| null	URL notified when the crawl ends.
`created_at`	string	When it was created (ISO 8601, UTC).
`started_at`	string \| null	When the work started.
`completed_at`	string \| null	When it ended.
`expires_at`	string \| null	When the result is deleted (plan's result retention).
`data_expired`	boolean	true once the results were deleted (plan retention): result endpoints answer 410.
`reports`	array	Each report: {name, status (queued, running, completed, failed, skipped), url}.
`links`	object	URLs of the result endpoints of this crawl.

Errors

404crawl_not_found409crawl_finished401unauthorized403scope_denied429rate_limited

Crawled pages

GET /api/v1/crawls/{crawl_id}/pages

Every page crawled: status code, title, depth, load time and indexability.

Credits Free Sync answered in the request

Path parameters

Field name	Type	Description
`crawl_id`required	string	Id of the crawl (crl_…).

Query parameters

Field name	Type	Description
`status_code`optional	string	A status code (404) or class (4xx).
`limit`optional	integer	Rows per page. Default: `100` Range: 1 to 500
`cursor`optional	string	next_cursor of the previous page.

Response fields

Field name	Type	Description
`object`	string	Always list.
`data`	array	The rows of this page of results.
`data[].url`	string	URL the request was made for.
`data[].status_code`	integer	HTTP status code (0: unreachable).
`data[].title`	string	Page title.
`data[].depth`	integer	Clicks from the start page.
`data[].load_time_ms`	integer	Load time in milliseconds.
`data[].content_type`	string	Content-Type of the response.
`data[].indexable`	boolean	Whether search engines can index the page.
`data[].indexability_reason`	string \| null	Why the page is not indexable.
`data[].noindex`	boolean	The page has a noindex robots directive.
`data[].nofollow`	boolean	The page has a nofollow robots directive.
`data[].robots_blocked`	boolean	robots.txt blocks the page.
`data[].canonical_url`	string \| null	Canonical URL of the page.
`has_more`	boolean	true when another page follows.
`next_cursor`	string \| null	Pass it as cursor to get the next page; null on the last page.

Errors

404crawl_not_found410crawl_expired400invalid_cursor401unauthorized403scope_denied429rate_limited

Site audit issues

GET /api/v1/crawls/{crawl_id}/issues

Site audit issue counts per page (pages with at least one issue). Needs the site_audit report.

Credits Free Sync answered in the request

Path parameters

Field name	Type	Description
`crawl_id`required	string	Id of the crawl (crl_…).

Query parameters

Field name	Type	Description
`type`optional	string	Only pages with this issue. Allowed: `missing_titles`, `duplicate_titles`, `missing_descriptions`, `duplicate_descriptions`, `missing_h1_tags`, `multiple_h1_tags`, `duplicate_h1_tags`, `missing_alt_tags`, `missing_canonical`, `mismatch_canonical`, `hreflang`, `broken_links_4xx_link`, `server_error_5xx_link`, `no_index_robot`
`limit`optional	integer	Rows per page. Default: `100` Range: 1 to 500
`cursor`optional	string	next_cursor of the previous page.

Response fields

Field name	Type	Description
`object`	string	Always list.
`data`	array	The rows of this page of results.
`data[].url`	string	URL the request was made for.
`data[].issues`	object	Count of each site audit issue on the page: missing_titles, duplicate_titles, missing_descriptions, duplicate_descriptions, missing_h1_tags, multiple_h1_tags, duplicate_h1_tags, missing_alt_tags, missing_canonical, mismatch_canonical, hreflang, broken_links_4xx_link, server_error_5xx_link.
`data[].no_index_robot`	boolean	The page is blocked from indexing.
`has_more`	boolean	true when another page follows.
`next_cursor`	string \| null	Pass it as cursor to get the next page; null on the last page.

Errors

404report_not_requested400invalid_issue_type404crawl_not_found410crawl_expired400invalid_cursor401unauthorized403scope_denied429rate_limited

Broken links

GET /api/v1/crawls/{crawl_id}/links

Broken internal pages and broken external links, with the pages linking to them. Internal links come first.

Credits Free Sync answered in the request

Path parameters

Field name	Type	Description
`crawl_id`required	string	Id of the crawl (crl_…).

Query parameters

Field name	Type	Description
`status`optional	string	A status code (404) or class (4xx, 5xx). Default: every 4xx / 5xx and unreachable (0) link.
`type`optional	string	Only internal or external links. Allowed: `internal`, `external`
`limit`optional	integer	Rows per page. Default: `100` Range: 1 to 500
`cursor`optional	string	next_cursor of the previous page.

Response fields

Field name	Type	Description
`object`	string	Always list.
`data`	array	The rows of this page of results.
`data[].url`	string	The broken link's target.
`data[].type`	string	internal (a page of the site) or external.
`data[].status_code`	integer	HTTP status code (0: unreachable).
`data[].anchor_text`	string \| null	Link text (external links).
`data[].source_pages`	array	Pages linking to it (up to 20).
`data[].source_page_count`	integer	Number of pages linking to it.
`has_more`	boolean	true when another page follows.
`next_cursor`	string \| null	Pass it as cursor to get the next page; null on the last page.

Errors

404crawl_not_found410crawl_expired400invalid_cursor401unauthorized403scope_denied429rate_limited

A report

GET /api/v1/crawls/{crawl_id}/reports/{report}

Summary and per-page rows of one report of the crawl. While the report runs: status queued / running, summary null and no rows. The sample is the site_audit report.

Credits Free Sync answered in the request

Path parameters

Field name	Type	Description
`crawl_id`required	string	Id of the crawl (crl_…).
`report`required	string	A report requested for the crawl. Allowed: `site_audit`, `broken_links`, `page_index`, `schema`, `source_code`, `readability`, `accessibility`, `performance`

Query parameters

Field name	Type	Description
`limit`optional	integer	Rows per page. Default: `100` Range: 1 to 500
`cursor`optional	string	next_cursor of the previous page.
`status / type`optional	string	broken_links only: the filters of the links endpoint.

Response fields

Field name	Type	Description
`object`	string	Always crawl_report.
`crawl_id`	string	The crawl's id.
`report`	string	Report name.
`status`	string	Status of the report: queued, running, completed, failed or skipped.
`summary`	object \| null	Totals of the report (null until it has run).
`data`	array	Per-page rows of the report.
`has_more`	boolean	true when another page follows.
`next_cursor`	string \| null	Pass it as cursor to get the next page; null on the last page.

Errors

404unknown_report404report_not_requested404crawl_not_found410crawl_expired400invalid_cursor401unauthorized403scope_denied429rate_limited

Export

GET /api/v1/crawls/{crawl_id}/export

A file of the crawl's pages and results. The first call starts building it (202 with Retry-After); call again until it is ready, then download the signed URL (no API key needed).

Credits Free Sync answered in the request

Path parameters

Field name	Type	Description
`crawl_id`required	string	Id of the crawl (crl_…).

Query parameters

Field name	Type	Description
`format`optional	string	File format. Default: `"csv"` Allowed: `csv`, `json`

Response fields

Field name	Type	Description
`object`	string	Always crawl_export.
`crawl_id`	string	The crawl's id.
`format`	string	csv or json.
`status`	string	processing while the file is built, then ready.
`url`	string	Signed download URL (no API key needed) once ready.
`expires_in`	integer	Seconds the download URL stays valid.
`size_bytes`	integer	Size of the file.
`retry_after`	integer	While processing: seconds to wait before asking again.

Errors

409crawl_not_finished410crawl_expired404crawl_not_found401unauthorized403scope_denied429rate_limited

Compare two crawls

GET /api/v1/crawls/{crawl_id}/diff/{previous_id}

Two finished crawls of the same website: pages added, removed, status code changes and the change of each site audit issue.

Credits Free Sync answered in the request

Path parameters

Field name	Type	Description
`crawl_id`required	string	Id of the crawl (crl_…).
`previous_id`required	string	The earlier crawl (crl_…).

Query parameters

Field name	Type	Description
`section`optional	string	Pages listed in data. Default: `"added"` Allowed: `added`, `removed`, `status_changed`
`limit`optional	integer	Rows per page. Default: `100` Range: 1 to 500
`cursor`optional	string	next_cursor of the previous page.

Response fields

Field name	Type	Description
`object`	string	Always crawl_diff.
`crawl_id`	string	The crawl's id.
`previous_crawl_id`	string	The earlier crawl compared with.
`section`	string	added, removed or status_changed.
`summary`	object	pages_before, pages_after, pages_added, pages_removed, status_changes and issues (before / after / change of each site audit issue, null without site_audit).
`data`	array	The pages of the section: url, status_code (and previous_status_code).
`has_more`	boolean	true when another page follows.
`next_cursor`	string \| null	Pass it as cursor to get the next page; null on the last page.

Errors

400invalid_diff409crawl_not_finished404crawl_not_found410crawl_expired400invalid_cursor401unauthorized403scope_denied429rate_limited

Account

GET /api/v1/account/

The partner, the calling key, the credit balance, the plan's limits and the jobs and crawls running now.

Credits Free Sync answered in the request

Request parameters

None.

Response fields

Field name	Type	Description
`partner`	object	The partner account: id, name, company, email.
`key`	object	The API key of the call: prefix, name, mode (live / test), scopes.
`credits`	object	balance: credits available now.
`plan`	object	The plan and its limits.
`plan.name`	string	Plan name.
`plan.monthly_credits`	integer	Credits added on each renewal.
`plan.requests_per_minute`	integer	Rate limit per minute (all keys of the account).
`plan.requests_per_day`	integer	Rate limit per rolling 24 hours.
`plan.max_pages_per_crawl`	integer	Largest max_pages of a crawl.
`plan.max_concurrent_crawls`	integer	Live crawls running at once.
`plan.max_crawls_per_day`	integer	Live crawls started per rolling 24 hours.
`plan.max_concurrent_jobs`	integer	Live async jobs queued or running at once.
`plan.result_retention_days`	integer	Days job results and crawl data are kept.
`active`	object	Jobs and crawls running now.

Errors

401unauthorized403scope_denied429rate_limited

Usage

GET /api/v1/usage/

Requests and credits of live keys per day and per check over a date range.

Credits Free Sync answered in the request

Query parameters

Field name	Type	Description
`from`optional	string	First day, YYYY-MM-DD. Default: 29 days before to.
`to`optional	string	Last day, YYYY-MM-DD (at most 366 days after from). Default: today.

Response fields

Field name	Type	Description
`from`	string	First day of the range.
`to`	string	Last day of the range.
`totals`	object	Requests and credits of the whole range (live keys).
`by_day`	array	{date, requests, credits} per day with traffic.
`by_check`	array	{product, check, requests, credits} per check, most credits first.

Errors

400invalid_date401unauthorized403scope_denied429rate_limited

Credit transactions

GET /api/v1/credits/transactions/

The credit statement, newest first: top-ups, plan credits, reservations, releases and adjustments, each with the balance after it.

Credits Free Sync answered in the request

Query parameters

Field name	Type	Description
`limit`optional	integer	Rows per page. Default: `50` Range: 1 to 200
`before`optional	integer	next_before of the previous page (a transaction id).

Response fields

Field name	Type	Description
`data`	array	Ledger rows, newest first: id, kind (topup, plan, reserve, release, charge, adjust), amount (negative: debit), balance_after, reference (job / crawl / check id), note, created_at.
`has_more`	boolean	true when another page follows.
`next_before`	integer \| null	Pass it as before to get the next page.

Errors

400invalid_request401unauthorized403scope_denied429rate_limited

Pricing

GET /api/v1/pricing/

The current credits of every check, of a crawled page and of every crawl report.

Credits Free Sync answered in the request

Request parameters

None.

Response fields

Field name	Type	Description
`data`	array	{code, credits, unit, description} of every price: page.<check>, crawl.page, crawl.report.<report>.

Errors

401unauthorized429rate_limited