# OnPage audit

> Run an audit and interpret page scores and Lighthouse findings.

Canonical: https://docs.georanker.com/docs/seo-tools-api-onpage

Run an OnPage audit to see why a particular URL loads slowly or fails a Lighthouse check. GeoRanker uses Google PageSpeed Insights and keeps separate samples for mobile and desktop. Use a publicly accessible URL, including `https://`.

## Create an audit and get the result

With your key in `SEO_TOOLS_API_KEY`, run the following commands in a shell with curl and jq. A successful create request returns HTTP 201 and an `id`. Use that ID to read the audit again as it runs.

```bash
API='https://seoapi.georanker.com'
AUDIT_ID=$(curl --fail-with-body -sS "$API/api/onpage" \
  -H "Authorization: Bearer $SEO_TOOLS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "url": "https://example.com/",
    "devices": ["mobile", "desktop"],
    "isRecurring": false
  }' | jq -er '.id')

curl --fail-with-body -sS "$API/api/onpage/$AUDIT_ID" \
  -H "Authorization: Bearer $SEO_TOOLS_API_KEY" | jq .
```

`url` is the required request field. Omit `devices` to audit both strategies, or send `["mobile"]` or `["desktop"]` to check one. For a weekly audit, set `isRecurring` to `true` and `scheduleDays` to `7`.

## Read the Lighthouse results

The public GET schema describes a JSON object. The SEO Tools viewer reads a numeric `status`, a mobile sample in `mFirstSample` and a desktop sample in `dFirstSample`. It refreshes while status is `0` or `1`, reads the samples at `2` and shows a failure at `3`. On failure, check that PageSpeed Insights can reach the URL. A single-device audit may only have the sample for the device you requested.

This shortened example shows part of a completed mobile audit with illustrative values. Each sample can contain the requested and final URLs, the capture time, category scores and individual audits.

```json
{
  "url": "https://example.com/",
  "status": 2,
  "mFirstSample": {
    "requestedUrl": "https://example.com/",
    "finalUrl": "https://example.com/",
    "categories": {
      "performance": { "score": 0.66 },
      "accessibility": { "score": 1 },
      "best-practices": { "score": 1 },
      "seo": { "score": 1 }
    },
    "audits": {
      "largest-contentful-paint": {
        "title": "Largest Contentful Paint",
        "displayValue": "7.9 s"
      }
    }
  }
}
```

The example's mobile performance score displays as 66 out of 100. Largest Contentful Paint was 7.9 seconds. Use the individual audit findings to find which resources or redirects contributed to the delay. Compare runs for the same device and final URL after a change.

To find audits associated with an existing project, use `GET /api/projects/{projectId}/onpage` and read the `reports` array. The public create schema lists URL, devices and scheduling fields. The signed-in app also supplies a campaign ID when an audit is created inside a project. [OnPage API reference](https://seoapi.georanker.com/api/docs#/OnPage)

[SEO Tools API overview](https://docs.georanker.com/docs/seo-tools-api)
