Acumen API (v1)

Who it's for: Engineers and operators who want to pull Acumen monitoring data into scripts, dashboards, data warehouses or AI tools.
You'll learn: How to create an API key, authenticate, list projects and monitors, fetch check history, and handle errors.

The Acumen API is a read-only HTTP API. Use it to extract the same monitoring data you see in the dashboard without scraping the UI.


Prerequisites

  • An Acumen Logs account on a paid plan (API access is not available on the free plan).
  • Permission to open Account > API Keys (account owners and organisation users on the billing account).
  • Optional: a tool that can send HTTP requests with a bearer token (curl, Postman, your own script).

Create an API key

  1. Sign in to Acumen Logs.
  2. Open Account > API Keys.
  3. Enter a short Name (for example Reporting script or Claude MCP).
  4. Choose an Expiry: never, 30 days, 90 days, or 365 days.
  5. Click Generate key.
  6. Copy the key immediately. It is only shown once.

The keys table shows each key's name, created time, last used time and expiry. Click Revoke to invalidate a key at any time. Mobile app login tokens are separate and are never listed or revoked from this page.


Authentication

Send the key on every request as a bearer token:

Authorization: Bearer <your-api-key>
Accept: application/json

Keys are issued with the read ability only. There are no write endpoints in v1.

Situation HTTP status
Missing, invalid, revoked or expired key 401
Account no longer has a paid plan 402
Token without the read ability 403

Team members who create a key only receive data for projects and monitors they already have permission to view in the dashboard.


Base URL and conventions

Item Value
Base URL https://app.acumenlogs.com/api/v1
Format JSON
Timestamps UTC, ISO-8601 style strings
Methods GET only
Scoping Same access rules as the dashboard

Credentials, custom headers, request bodies, synthetic journey steps, API monitor journeys and heartbeat pulse URLs are never returned.


Pagination and filters

List endpoints return Laravel's standard pagination envelope:

{
  "data": [ ... ],
  "links": {
    "first": "...",
    "last": "...",
    "prev": null,
    "next": "..."
  },
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 120,
    "last_page": 5
  }
}
Parameter Applies to Description
page All lists Page number (default 1)
per_page All lists Items per page, 1–100 (default 25)
site_id Monitor lists Only monitors in this project
active Monitor lists true or false
from, to /checks Date or date-time range, e.g. 2026-11-01 or 2026-11-01 12:00:00
status /checks pass or fail (for heartbeats, fail means late pulses)

Rate limits and errors

Each API key can make 60 requests per minute. Exceeding the limit returns 429 with a Retry-After header.

Status Meaning
401 Missing, invalid, revoked or expired key
402 The account does not have an active paid plan
403 The key does not have the read ability
404 The resource does not exist or you do not have access
422 Invalid query parameters
429 Rate limit exceeded

Error bodies look like:

{
  "message": "Unauthenticated."
}

Validation errors (422) include a errors object keyed by parameter name.


Endpoints

Account

Method Path Description
GET /me The authenticated user, plan name and the key used for the request

Projects (sites)

Method Path Description
GET /sites Projects with monitor counts
GET /sites/{id} A single project

Monitors

Every monitor type shares the same three endpoints:

Method Path Description
GET /{type} List monitors
GET /{type}/{id} Monitor configuration and current state
GET /{type}/{id}/checks Check history, newest first
{type} Product Check history contains
uptime Uptime Pass/fail, status code, response time, TTFB, DNS time, region, failure message
synthetic Synthetic journeys Each run: pass/fail, warnings, region, response counts by status class
api-monitors API monitors Pass/fail, total time, response time, request count, region, failure message
ssl SSL certificates When the certificate was checked (current certificate details are on the monitor)
whois Domain expiry (WHOIS) When the domain was checked (current expiry details are on the monitor)
heartbeats Heartbeats Each received pulse and whether it was late

Status pages

Method Path Description
GET /status-pages Status pages and the monitors shown on them
GET /status-pages/{id} A single status page
GET /status-pages/{id}/announcements Announcements; optional status filter (e.g. published)

Response fields

/me

Field Description
id, name, email, timezone Account profile
plan Current plan name
api_key.name Display name of the key used for this request
api_key.abilities Always ["read"] for keys created in settings
api_key.expires_at Expiry timestamp, or null

Projects (/sites)

Field Description
id, name Project identity
monitor_counts Counts for uptime, synthetic, api_monitors, ssl, whois, heartbeats
created_at, updated_at Timestamps

Shared monitor fields

Most monitors include id, type, name, site_id, nested site (id, name), scheduling fields (interval, interval_type, run_regions, last_run, next_run), active, and where applicable last_test_passed.

Type Extra fields of note
uptime check_type, url, protocol, port, request_method, expected_status, max_load_time_ms, content_search
synthetic url, base_page_url, device (active maps to schedule enabled)
api_monitor step_count (journey steps themselves are omitted)
ssl domain, host, issuer, days_left, valid_from, valid_to, fingerprint, domains, tls_version_support, errors
whois domain, expiration_date, days_left, registrar, nameservers, last_checked_at
heartbeat grace_period, grace_period_time_unit, last_beat_at, next_expected_beat_at (pulse URL omitted)

Check history highlights

Type Notable fields
Uptime passed, status_code, response_time_ms, ttfb_ms, dns_resolve_time_ms, resolved_ip, run_region, failed_message, created_at
Synthetic passed, has_warnings, status, running, run_region, start_url, response_count, console_log_count, responses_by_status (2xx–5xx), created_at
API monitor passed, total_time_ms, total_response_time_ms, total_requests, run_region, failed_message, created_at
SSL / WHOIS created_at only — current certificate or expiry state is on the monitor
Heartbeat was_late, created_at

Status pages

Field Description
name, slug, custom_domain, active Public page identity
password_protected, announcements_enabled Feature flags (password value is never returned)
monitors[] { "type": "uptime"|"synthetic"|"ssl", "id": ... }

Announcements include title, body, status, show_on_status_page, published_at.


Examples

Confirm the key works:

curl -sS -H "Authorization: Bearer $ACUMEN_API_KEY" \
  "https://app.acumenlogs.com/api/v1/me"

List projects:

curl -sS -H "Authorization: Bearer $ACUMEN_API_KEY" \
  "https://app.acumenlogs.com/api/v1/sites"

List active synthetic tests in a project:

curl -sS -H "Authorization: Bearer $ACUMEN_API_KEY" \
  "https://app.acumenlogs.com/api/v1/synthetic?site_id=42&active=true"

List failing uptime checks for the last week:

curl -sS -H "Authorization: Bearer $ACUMEN_API_KEY" \
  "https://app.acumenlogs.com/api/v1/uptime/123/checks?status=fail&from=2026-11-07&per_page=100"

Fetch published status-page announcements:

curl -sS -H "Authorization: Bearer $ACUMEN_API_KEY" \
  "https://app.acumenlogs.com/api/v1/status-pages/9/announcements?status=published"

Best practices

  • One key per consumer. Create separate keys for each script, AI agent or environment so you can revoke one without affecting others.
  • Prefer short expiry. Use 30 or 90 days for experiments; rotate production keys on a schedule.
  • Store keys as secrets. Prefer environment variables or a secrets manager — never commit keys to git.
  • Page with per_page=100. Reduce round trips when backfilling history, and respect the 60 req/min limit.
  • Filter early. Use site_id, active, from/to and status so you pull less data than you need.
  • Treat 404 as “no access”. Resources outside your permissions look the same as missing ones.

Troubleshooting

Symptom Likely cause What to do
401 Unauthenticated Key missing, mistyped, revoked or expired Generate a new key from Account > API Keys and update Authorization
402 Payment Required Free plan or cancelled subscription Upgrade at Subscription, then retry
403 Token was created without the read ability Create a new key from the API Keys page (mobile login tokens are not for this API)
404 on a monitor you can see in the UI Wrong ID, or your team role lacks access to that project Confirm the ID from /sites / /{type} and check team permissions
Empty data array Filters exclude everything, or the account has no monitors of that type Drop site_id / active / date filters and retry
429 More than 60 requests per minute for this key Back off using Retry-After, or spread work across keys carefully
Key not shown after leaving the page Plain-text key is only displayed once Revoke the old key and generate a new one

Need help?

Contact support@acumenlogs.com with the key name (never the secret), the request path and the HTTP status you received.