getReport API

Email hello@getreport.app with the site or project you will use it for. Keys are free and start with gr_. Send it in every request that starts a report:

Authorization: Bearer gr_…

Reading a report, its PDF, its fixes and badges needs no key: report links are shareable.

# 1. Start a report (or get the cached one)
curl -s https://api.getreport.app/api/v1/reports \
  -H "Authorization: Bearer $GETREPORT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/"}'
# → {"id":"PINUz7tvTi","status":"queued","cached":false,"coalesced":false}

# 2. Read it; repeat until status is done, partial or failed (20-60 s)
curl -s https://api.getreport.app/api/v1/reports/PINUz7tvTi

The same in Node.js 18 or later:

const api = 'https://api.getreport.app/api/v1/reports';
const res = await fetch(api, {
  method: 'POST',
  headers: { authorization: `Bearer ${process.env.GETREPORT_KEY}`, 'content-type': 'application/json' },
  body: JSON.stringify({ url: 'https://example.com/' }),
});
let report = await res.json();
while (!['done', 'partial', 'failed'].includes(report.status)) {
  await new Promise((r) => setTimeout(r, 3000));
  report = await (await fetch(`${api}/${report.id}`)).json();
}
console.log(report.scores.overall, report.topFixes.map((f) => f.title));

To follow a report live instead of polling, open GET /api/v1/reports/{id}/events as server-sent events.

Show your latest scores on your own site: a small card with the grade and every module, linking to the full report. It updates when you run a new check, loads no script and sets no cookie.

<iframe src="https://api.getreport.app/embed/example.com"
  title="Website checkup scores by getReport"
  width="560" height="120" loading="lazy"
  style="border:0;max-width:100%"></iframe>

Replace example.com with your domain. For a smaller mark, the score badge is an SVG image: https://api.getreport.app/badge/example.com.svg.

Check your site on every deploy and fail the build when a score drops below your minimum. The scores and a link to the full report appear in the job summary.

- uses: getreport/action@v1
  with:
    url: https://example.com/
    api-key: ${{ secrets.GETREPORT_API_KEY }}
    min-score: 80
    thresholds: speed=70, seo=90

Store your key as the GETREPORT_API_KEY secret. Every input is described at github.com/getreport/action.

• 100 new reports per key in any 24 hours. Every POST /api/v1/reports answer made with a key carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds).
• A report of the same page, device and location from the last 12 hours comes back at once with "cached": true and does not count. Add "force": true to run again.
• Each site can be checked 5 times an hour, whoever asks, so the sites we check are never flooded.
• A 429 answer says how long to wait in Retry-After.

Base URL https://api.getreport.app. The full description, with every field, is the OpenAPI 3.1 file: /api/openapi.json.

POST /api/v1/reportskey

Start a report, or get the cached one. Returns 202 with the new id, or 200 when a report of the same page, device and location from the last 12 hours exists (cached) or is still running (coalesced). Poll GET /api/v1/reports/{id} until status is done, partial or failed; most reports take 20-60 s.

GET /api/v1/reports/{id}

Read a report. The full report: scores, every module with its findings, the plain-language fix for each, and links to the HTML page, PDF and badge. The same JSON as getreport.app/r/{id}.json.

GET /api/v1/reports/{id}/events

Follow a running report (server-sent events). A text/event-stream with one event per module status change and a final `report` event. Use it instead of polling.

POST /api/v1/comparekey

Start reports for 2-5 sites at once. One report per site, each cached and counted like POST /api/v1/reports.

GET /api/v1/domains/{host}

Scores over time for a site. Finished reports and crawls for the host, newest first: date, device and scores, crawl page and issue counts, plus whether the domain is verified and indexed (never the verification token). Report and crawl ids come only with the verified owner's grant in `x-owner-grant`.

POST /api/v1/domains/{host}/verify

The token for a domain and the three ways to publish it. Returns the TXT record, the meta tag and the file to publish. The token stays the same for the domain.

POST /api/v1/domains/{host}/verify/check

Look for the token and verify the domain for 12 months. Checks DNS, then the meta tag on the home page, then /.well-known/getreport.txt. On success the answer carries an owner grant for the settings call; 422 lists what was tried.

POST /api/v1/domains/{host}/plugin-key

Verify the domain and get an API key that may check this site only. Used by the getReport WordPress plugin when you click Connect: the same check as verify/check (the plugin publishes the token from verify first), then a key limited to this site and its www twin, 20 new reports a day. The key is shown once; reconnecting revokes the earlier one.

PUT /api/v1/domains/{host}/settings

Let search engines index the reports of a verified domain. Needs the owner grant from the check in the x-owner-grant header, and a verification that has not run out.

GET /api/v1/reports/{id}/pdf

The report as a PDF.

GET /api/v1/reports/{id}/fixes.{format}

The fixes as a Markdown checklist or a CSV. Markdown pastes into a GitHub issue; the CSV imports into Trello or Jira.

GET /badge/{host}.svg

A score badge for a README or website. The latest overall score, or one module’s. Cached for 24 hours.

GET /api/v1/status

Queue depth, worker health and today’s speed-test quota.

Errors are application/problem+json with a readable title and a stable code:

• INVALID_URL: The address is not a web page address.
• INVALID_API_KEY: The key is unknown or revoked.
• PRIVATE_ADDRESS: The address points to a private network.
• UNREACHABLE: The host does not resolve or answer.
• SITE_BLOCKED: The site’s owner asked us not to check it.
• RATE_LIMITED_KEY: The key started 100 new reports in the last 24 hours.
• RATE_LIMITED_HOST: The site was checked 5 times in the last hour.

Check sites you run or work on, and link to the report when you show its results: every report has a page at getreport.app/r/{id}. We check each site the way described on our crawler page, and site owners can opt out.