> For the complete documentation index, see [llms.txt](https://help.rankability.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.rankability.com/api/api-use-cases.md).

# 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](/api/api-researcher.md)             | Asynchronous job           |
| Score an existing page against search competitors | [Optimize API](/api/api-optimize-endpoint.md)        | Synchronous analysis       |
| Audit one page with scored findings and gates     | [Page Auditor API](/api/api-page-auditor.md)         | Asynchronous audit         |
| Crawl a site and inventory technical issues       | [Site Auditor API](/api/api-site-auditor.md)         | Asynchronous project crawl |
| Fetch one page without a complete site audit      | [Scrape API](/api/api-crawler.md)                    | Synchronous fetch          |
| Crawl a bounded set of pages for raw page data    | [Crawl API](/api/api-crawler.md)                     | Asynchronous bounded crawl |
| Ask a grounded question or extract fields         | [Extract API](/api/api-crawler.md)                   | Synchronous extraction     |
| Read tracking data for dashboards                 | [Tracker API](/api/api-reporter-getting-started.md)  | Read requests              |
| Create optimized content                          | [Copywriter jobs](/api/api-creating-content-jobs.md) | 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](/api/api-researcher.md).

## 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](/api/api-reporter-getting-started.md) 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](/api/api-authentication.md) and [API usage, rate limits, and errors](/api/api-credits-rate-limits-and-errors.md) before moving an integration into production.