API use cases and integration patterns

Choose an API surface based on the result you need. Similar-looking Rankability operations can have different scopes, usage impact, execution time, and outputs.

Choose the right surface

You need to…	Use	Execution model
Discover and cluster keyword opportunities	Researcher API	Asynchronous job
Score an existing page against search competitors	Optimize API	Synchronous analysis
Audit one page with scored findings and gates	Page Auditor API	Asynchronous audit
Crawl a site and inventory technical issues	Site Auditor API	Asynchronous project crawl
Fetch one page without a complete site audit	Scrape API	Synchronous fetch
Crawl a bounded set of pages for raw page data	Crawl API	Asynchronous bounded crawl
Ask a grounded question or extract fields	Extract API	Synchronous extraction
Read tracking data for dashboards	Tracker API	Read requests
Run a one-time prospect visibility report without a workspace	Prospect reports API	Asynchronous report
Create optimized content	Copywriter jobs	Asynchronous content job

Keyword-research workflow

1. Create a key with researcher:run and researcher:read.
2. Submit one to 20 topics and the appropriate research mode.
3. Store the returned job_id and whether the response was cached.
4. Poll until completed, empty, or failed.
5. Use the completed result directly, or separately read saved Researcher projects.

Do not assume creating an API research job automatically creates a saved Researcher project. See Researcher API.

Tracking and dashboard workflow

Start read-only. A dashboard normally needs only reporter:read:

1. List projects.
2. Read project detail for SPI and current platform coverage.
3. Read results using the default latest_per_platform snapshot.
4. Read trends for completed and partial terminal runs.
5. Use the organization or brand summary only when its aggregation matches the report you are building.

Add reporter:run only if the integration must trigger scans. Add reporter:write only if it must create, change, or delete projects. These legacy scope names authorize Tracker. Read Tracker API onboarding before automating scans.

Audit workflow

Use Page Auditor when one URL and target keyword need scored page-level recommendations. Use Site Auditor when a domain needs a multi-page crawl, issue inventory, and page evidence.

For Site Auditor:

1. Estimate the crawl’s pooled usage impact.
2. Create the project, which starts the first crawl.
3. Poll the project until a terminal state.
4. Read its pages and issues.
5. Cancel before deleting an in-progress crawl.

Site Auditor and the bounded Crawler API are not interchangeable. Site Auditor produces audit issues and summary metrics; Crawl returns crawler job pages and fetch diagnostics.

Fetch and extraction workflow

Use Scrape when you need one fetched page with SEO/AEO data. Use Crawl for a bounded, same-domain collection. Use Extract when you need a grounded answer, relevant passages, or caller-defined fields from a URL, an existing crawler page, or supplied content.

Check /crawler/usage before large jobs. A crawl reserves its maximum page budget against the daily page quota; that page quota is separate from the account’s pooled usage windows.

Reliability pattern

For every integration:

1. Use a separate least-privilege key.
2. Record X-Request-Id and limit headers.
3. Send Idempotency-Key where supported.
4. Persist returned IDs before polling.
5. Back off polling and stop at terminal states.
6. Distinguish a missing result from a failed or still-running job.
7. Confirm usage and partial-result behavior before retrying.
8. Require the human review appropriate to generated content or high-impact actions.

Returned headers are authoritative. Integrations should not encode plan names or assumed limits.

Review Authentication and API scopes and API usage, rate limits, and errors before moving an integration into production.