> 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 the correct Rankability API workflow and design reliable content, research, reporting, audit, and crawler integrations.

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.