Pull a metric from any JSON API on a schedule

Some numbers already sit behind an API: a dashboard tool’s stats endpoint, a billing system’s summary, an internal service your team built. Instead of writing a job to push them into Clarion, you can have Clarion pull them. Each metric can have one URL that Clarion fetches on a schedule, recording one number from the response.

How it works

On the metric’s Edit Metric dialog, the Fetch from URL section takes four settings:

• JSON URL (https) — the address to fetch.
• Path to the number — a dot path into the response, like data.totals.revenue or items[0].count. Leave it blank if the whole response is the number.
• Auth header — optional, one header such as Authorization: Bearer … or X-Api-Key: ….
• How often — every hour, every 6 hours or every day.

Press Test to fetch once and see the number Clarion found, without recording it. Press Save and the first fetch runs within a minute. Each fetch writes the value to the metric’s current day, week or month, replacing the earlier value for that period, and fires the metric.ingested webhook.

What the endpoint has to return

Clarion reads JSON only. The value at your path can be a number or a numeric string like "1,234". Anything else — HTML, CSV, "$12k", an object — is reported as an error and nothing is recorded.

The request Clarion sends is a GET with Accept: application/json and User-Agent: Clarion-Metrics/1.0 (+https://onclarion.com). The response must arrive within 5 seconds and be under 256 KB. Redirects aren’t followed, so give Clarion the final URL — a 3xx counts as a failure.

Safe by design

Because this feature makes Clarion send requests on your company’s behalf, it has guard rails:

• Admins only. Only owners and admins can set up, change or remove a source. Everyone can see where a metric’s values come from. See roles and permissions.
• The credential stays put. The header value is stored encrypted and never displayed again. If someone changes the URL to a different host, the saved credential is removed rather than sent to the new host.
• Public hosts only. URLs must be https:// on port 443 with no username or password in them. Addresses that resolve to private, loopback or other internal networks are refused, and that check runs on every fetch.
• Errors without leaks. When a fetch fails, the metric shows a short reason — The server answered HTTP 401. or Nothing found at "data.total". — and never the response body. After 10 failures in a row the source pauses; saving it again resumes it.

When to pull, when to push

Pull suits numbers that are already exposed as JSON and only need checking a few times a day. If the number lives somewhere that can’t serve JSON — a spreadsheet, for instance — push it instead with a push URL; the Google Sheets recipe shows how. If you need values faster than hourly or for many metrics at once, use the ingest API.

Step-by-step setup: Pull metrics from a URL.