GET /v1/ping

Single-request convenience over POST /v1/heartbeats. Everything goes in the query string, response is OK\n, fits in a cron line. Used by shell scripts, n8n HTTP nodes, Lambda last lines, GitHub Actions steps.

GET requests are conventionally side-effect-free; this one creates database records. JSON bodies are too much friction for the calling environments that hit this endpoint.

https://eu.ingest.agentping.io/v1/ping

Query parameters

Parameter	Required	Description
`key`	Yes (or via header)	Ping token (`ping_...`, recommended) or full API key (`apk_...`, discouraged). See Authentication.
`agent`	Yes	Agent slug. New agents auto-created.
`status`	No (default `ok`)	`ok`, `fail`, `start`, `timeout`. `start` opens without finishing.
`cost_usd`	No	Numeric cost in US dollars.
`duration_ms`	No	If absent, computed from a prior `start` ping with the same `id`.
`id`	No	Client-generated run ID.
`metadata`	No	Single string up to 256 characters, stored as a `note`. Requires a metadata-eligible plan (Team or above); silently dropped on Starter. For richer, use `POST /v1/heartbeats`.

Response

200 OK with the smallest possible body:

OK

Pass Accept: application/json for the full JSON response:

{
  "id": "run_eu_018f3a2b9c1d7e8fa4b9c2d7e8f1a3b9",
  "agent": "daily-summary",
  "status": "ok",
  "received_at": "2026-05-15T14:32:12.450Z"
}

Failures use text/plain so they're readable in shell output:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

missing required parameter: agent

HTTP/1.1 401 Unauthorized
Content-Type: text/plain

This ping token is scoped to agent "daily-summary".
You attempted to fire a heartbeat for "competitor-scan".

Examples

Cron daily heartbeat:

0 9 * * *  /usr/bin/wget -qO- 'https://eu.ingest.agentping.io/v1/ping?key=ping_eu_018f3a2b9c1d7e8fa4b9c2d7e8f1a3b6&agent=daily-summary&status=ok'

Failure ping with cost and a note:

curl 'https://eu.ingest.agentping.io/v1/ping?key=ping_eu_018f3a2b9c1d7e8fa4b9c2d7e8f1a3b6&agent=invoice-sync&status=fail&cost_usd=0.011&metadata=stripe%20rate%20limit'

Header-auth variant for environments where query strings get logged:

curl -H "X-AgentPing-Key: ping_eu_018f3a2b9c1d7e8fa4b9c2d7e8f1a3b6" \
  'https://eu.ingest.agentping.io/v1/ping?agent=daily-summary&status=ok'

Authentication

Credential	When to use
`ping_<region>_...`	Recommended. Scoped to one agent, can only fire heartbeats. A leak compromises one agent's status.
`apk_<region>_...`	Accepted but strongly discouraged. Full team key in a URL leaks through access logs, shell history, browser history, referer headers.

The dashboard's "copy curl one-liner" always uses a ping_ token.

A credential whose region segment doesn't match the endpoint returns 401 Unauthorized before any database lookup. A ping token used against a non-scope agent returns 401 with both slugs named. See Authentication.