Oncrawl KPI Reader

The Oncrawl KPI Reader node reads a fixed set of validated crawl KPIs from one or several completed Oncrawl crawls, ready for analysis or reporting.

What does the Oncrawl KPI Reader node do?#

The Oncrawl KPI Reader reads a fixed set of crawl health indicators from one or several completed Oncrawl crawls, and returns them in a shape that drops straight into an LLM prompt, a template or an email.

It asks you for no query. The KPI list is fixed, the aggregations are built for you, and each requested KPI is checked against the crawl’s own schema first. That last point is what makes the output trustworthy: a KPI the crawl cannot produce is reported in unavailable_metrics with a reason, never returned as 0. In a report, a zero and an absence mean very different things, and conflating them is how a crawl problem gets read as a traffic problem.

For anything outside this KPI list — a filtered page list, a custom distribution, an export — use the Oncrawl Data Reader, which accepts an arbitrary OQL query.

Common use cases:

• Sending a recurring crawl health summary by email.
• Tracking total, fetched and indexable page counts over time.
• Comparing the same KPIs across the two most recent crawls in a single run.
• Getting a status code distribution without writing an aggregation.
• Triggering an alert when a KPI crosses a threshold.

Quick setup#

Available KPIs#

KPI	What it measures
Total pages	Pages known in the crawl
Fetched pages	Pages the crawler actually retrieved
Indexable pages	Pages considered indexable
Average Inrank	Average internal popularity score
Average load time	Average page load time
Status code distribution	Page count per HTTP status code

Configuration parameters#

Required fields#

Optional fields#

Output#

{
  "selection": { "mode": "latest", "count": 1 },
  "crawls": [
    {
      "provenance": {
        "project_id": "p1",
        "crawl_id": "abc123",
        "crawl_ended_at": 1720003600000,
        "retrieved_at": "2026-10-20T14:00:00+00:00",
        "source": "Oncrawl API v2"
      },
      "metrics": {
        "total_pages": 12000,
        "fetched_pages": 11800,
        "avg_inrank": 4.5
      },
      "distributions": {
        "status_code": { "200": 11000, "404": 800 }
      },
      "unavailable_metrics": [],
      "raw_metadata": { "fields": [] }
    }
  ]
}

Troubleshooting#

A KPI appears in unavailable_metrics instead of in metrics

Cause: The crawl’s schema does not expose the field that KPI needs — usually because the crawl configuration did not collect it.

Solution: The entry states which KPI and why. Either enable the corresponding data collection in the Oncrawl crawl settings, or drop that KPI from the selection.

Oncrawl crawl is not completed

Cause: The selected crawl is still running or failed.

Solution: Wait for it to finish, or switch to Always use the latest crawls, which only ever reads completed crawls.

Oncrawl rejected the token as unauthenticated (401)

Cause: The token is wrong or revoked. A valid token that is not allowed the action answers 403 instead.

Solution: Create a new token under Settings > Tokens in Oncrawl and reconnect the integration.

Oncrawl refused the request (403)

Cause: Oncrawl recognised the token but refused the action. The message names the reason Oncrawl gave:

• quota_error — the account’s quota does not allow the request.
• no_active_subscription — the account has no active subscription.
• feature_not_available — the plan does not include this feature, for example the API option.
• otherwise — the token lacks the projects:read scope, or access to this project.

Solution: Free up or raise the quota, renew the subscription or the plan, or regenerate the token with the projects:read scope on an account that can see the project.

Oncrawl rate limit exceeded (429)

Cause: Oncrawl answered 429 to three attempts in a row. The node retries a 429 or a 5xx error twice, a few seconds apart, before giving up. Oncrawl does not publish its rate limit.

Solution: Re-run later, and avoid starting several workflows that read Oncrawl at the same moment.

Best practices and pitfalls#

How does it fit into a workflow?#

graph LR
    Resolver[Oncrawl Crawl Resolver] --> KPI[Oncrawl KPI Reader]
    KPI --> LLM[LLM<br/>summarise crawl health]
    LLM --> Email[Email Sender]

Related nodes#