Agents

Create an agent

Creates a new agent for the authenticated project and returns 201. There is no slug field in the request: the slug is always derived from name, the same way for every creation path (this endpoint, the dashboard onboarding wizard, and the MCP register_agent tool), so the three surfaces can never produce a row shaped differently.

A brand-new agent owns no monitors: status is idle, monitor_count is 0, and last_seen is null.

post/api/v1/agents

Request

  • Base URL: https://app.lastping.dev
  • URL: https://app.lastping.dev/api/v1/agents
  • Auth: API key in header X-Api-Key

Request body

namestring required

Human-readable agent name. The slug is derived from this value. Surrounding whitespace is trimmed; at most 200 characters (not bytes) and no control or invisible characters (400 INVALID_NAME). Bytes that are not valid UTF-8 are replaced with U+FFFD when the request is decoded, and accepted.

descriptionstring

Optional free-text description.

Example request

{
  "name": "Nightly ETL bot",
  "description": "Runs the nightly ETL pipeline and owns its monitors."
}

Response

Agent created.

idstring uuid required

Unique agent identifier.

slugstring required

Stable project-scoped identifier, derived from name at creation and immutable thereafter.

namestring required

Human-readable name.

descriptionstring required

Free-text description (empty string if not set).

status'down' | 'blocked' | 'late' | 'running' | 'up' | 'pending' | 'idle' required

Rolled up live from the monitors this agent owns, worst status first: down > blocked > late > running > up > pending > idle. Paused and in-maintenance monitors never contribute: muting a monitor must neither hide a broken agent nor drag a healthy one down.

  • down — at least one owned, active monitor is down.
  • blocked — no active monitor is down, but at least one owned monitor has a run that is blocked on a human right now. This is an alert-class state, not merely informational: it is excluded from the informational alert rate limit precisely so it cannot be starved by high-volume traffic.
  • late — no active monitor is down or blocked, but at least one is late.
  • running — no active monitor is down, blocked or late, but at least one owned monitor has a run currently in flight.
  • up — no active monitor is down, blocked, late or running, and at least one is up.
  • pending — the agent owns at least one monitor, but none of its active monitors has ever reported (only ever seen new). This usually means the wiring is wrong — the agent registered but never pinged.
  • idle — the agent owns no monitors, or every monitor it owns is paused or in maintenance. There is nothing to judge yet.
monitor_countinteger required

Number of monitors this agent owns. 0 for an agent with no monitors.

last_seenstring date-time nullable

RFC 3339 timestamp: the latest ping or traced span across ALL monitors this agent owns, including paused and in-maintenance ones — this answers "when did I last hear from this agent at all", not "is it healthy". A span counts from the end time it reports, recorded at most once a minute per monitor. Null or omitted for an agent that has never received a ping or a span on any of its monitors.

created_atstring date-time required

RFC 3339 UTC timestamp when the agent was created.

Example response

{
  "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "slug": "nightly-etl-bot",
  "name": "Nightly ETL bot",
  "description": "Runs the nightly ETL pipeline and owns its monitors.",
  "status": "up",
  "monitor_count": 3,
  "last_seen": "2026-07-10T03:00:05Z",
  "spend_24h": {
    "cost_usd": "0.006600",
    "cost_source": "estimated",
    "tokens_in": 150,
    "tokens_out": 50,
    "runs": 1
  },
  "runs_7d": [
    {
      "day": "2026-09-14",
      "runs": 12
    }
  ],
  "usage_24h": {
    "day": "2026-09-20",
    "model": "claude-sonnet-4-5",
    "provider": "anthropic",
    "tokens_in": 182340,
    "tokens_out": 20411,
    "tokens_cache_read": 95012,
    "tokens_cache_write": 4100,
    "cost_usd": "0.853221",
    "cost_source": "estimated",
    "origin": "traces"
  },
  "top_dependencies": [
    {
      "kind": "database",
      "name": "postgresql",
      "direction": "out",
      "calls": 1480,
      "errors": 12,
      "error_rate": 0.0081,
      "p50_ms": 10,
      "p95_ms": 25,
      "series": [
        {
          "day": "2026-09-20",
          "calls": 210,
          "errors": 2
        }
      ]
    }
  ],
  "created_at": "2026-07-01T12:00:00Z"
}

Changes

No recorded changes to this operation across all 2 revisions of this API.