Agent Ping API

openapi: 3.1.0
info:
  title: Agent Ping API
  version: '2026-11-01'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-01: 15 operation(s) read from 23 public documentation page(s) (each
    operation names its page in x-source). This is not the provider''s published contract; Agent Ping has published no machine-readable contract
    that the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 6
    documentation: 9
    pages-with-code: 11
    pages-read: 23
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-01'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://agentping.io/docs/api/auth
  - https://agentping.io/docs/api/ping
  - https://agentping.io/docs/api/read
  - https://agentping.io/docs/api/runs
  - https://agentping.io/docs/api/errors
  - https://agentping.io/docs/api/events
  - https://agentping.io/docs/api/heartbeats
  - https://agentping.io/docs/api/rate-limits
  - https://agentping.io/docs/guides/mcp
  - https://agentping.io/docs/quickstart
  - https://agentping.io/docs/sdks/laravel
  - https://agentping.io/docs/integrations/curl
  - https://agentping.io/docs/integrations/zapier
  - https://agentping.io/docs/frameworks/vercel-ai
  - https://agentping.io/docs/frameworks/openai-agents
  - https://agentping.io/docs/integrations/laravel-ai-opentelemetry
  - https://agentping.io/docs/sdks/go
  - https://agentping.io/docs/sdks/python
  - https://agentping.io/docs/sdks/typescript
  - https://agentping.io/docs/guides/your-data
  - https://agentping.io/docs/guides/finding-runs
  - https://agentping.io/docs/guides/staging-and-production
  - https://agentping.io/docs/index
servers:
- url: https://eu.ingest.agentping.io
paths:
  /:
    get:
      operationId: get
      tags:
      - Api
      summary: GET /
      x-source: https://agentping.io/docs/integrations/laravel-ai-opentelemetry
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl\n n8n\n Make\n GitHub Actions\n Zapier\n Claude Routines\n Claude Code\n Alerts\n Alerts and Issues\n Alert channels\n\
          \ Investigation summaries\n API reference\n Authentication\n Runs\n Events\n Heartbeats\n GET /v1/ping\n Read API\n Rate limits\n Errors\n\
          \ Guides\n Your data\n Finding runs\n MCP server\n Staging and production\n Billing\n Plans and limits\n How evaluations work\n What\
          \ counts as an event\n Data retention\n "
  /v1:
    get:
      operationId: get_v1
      tags:
      - Api
      summary: GET /v1
      x-source: https://agentping.io/docs/api/read
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl\n n8n\n Make\n GitHub Actions\n Zapier\n Claude Routines\n Claude Code\n Alerts\n Alerts and Issues\n Alert channels\n\
          \ Investigation summaries\n API reference\n Authentication\n Runs\n Events\n Heartbeats\n GET /v1/ping\n Read API\n Rate limits\n Errors\n\
          \ Guides\n Your data\n Finding runs\n MCP server\n Staging and production\n Billing\n Plans and limits\n How evaluations work\n What\
          \ counts as an event\n Data retention\n "
    post:
      operationId: post_v1
      tags:
      - Api
      summary: POST /v1
      x-source: https://agentping.io/docs/api/runs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1Request'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1Response'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl\n n8n\n Make\n GitHub Actions\n Zapier\n Claude Routines\n Claude Code\n Alerts\n Alerts and Issues\n Alert channels\n\
          \ Investigation summaries\n API reference\n Authentication\n Runs\n Events\n Heartbeats\n GET /v1/ping\n Read API\n Rate limits\n Errors\n\
          \ Guides\n Your data\n Finding runs\n MCP server\n Staging and production\n Billing\n Plans and limits\n How evaluations work\n What\
          \ counts as an event\n Data retention\n "
  /v1/agents:
    get:
      operationId: get_v1_agents
      tags:
      - Agents
      summary: Every agent on the team with rolled-up health.
      x-source: https://agentping.io/docs/api/read
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1AgentsResponse'
      x-evidence:
        kind: documentation
  /v1/heartbeats:
    post:
      operationId: post_v1_heartbeats
      tags:
      - Heartbeats
      summary: Errors
      description: JSON endpoint for sending heartbeats; errors follow the common error envelope.
      x-source: https://agentping.io/docs/api/errors
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1HeartbeatsResponse'
      x-evidence:
        kind: documentation
  /v1/ping:
    get:
      operationId: get_v1_ping
      tags:
      - Ping
      summary: GET /v1/ping
      x-source: https://agentping.io/docs/api/auth
      parameters:
      - name: agent
        in: query
        required: false
        schema:
          type: string
      - name: key
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl\n n8n\n Make\n GitHub Actions\n Zapier\n Claude Routines\n Claude Code\n Alerts\n Alerts and Issues\n Alert channels\n\
          \ Investigation summaries\n API reference\n Authentication\n Runs\n Events\n Heartbeats\n GET /v1/ping\n Read API\n Rate limits\n Errors\n\
          \ Guides\n Your data\n Finding runs\n MCP server\n Staging and production\n Billing\n Plans and limits\n How evaluations work\n What\
          \ counts as an event\n Data retention\n "
    post:
      operationId: post_v1_ping
      tags:
      - Ping
      summary: POST /v1/ping
      x-source: https://agentping.io/docs/integrations/curl
      parameters:
      - name: agent
        in: query
        required: false
        schema:
          type: string
      - name: key
        in: query
        required: false
        schema:
          type: string
      - name: status
        in: query
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1PingRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl \n The lowest-common-denominator way to fire a heartbeat: one HTTP call, one finished run. For the full endpoint reference,\
          \ see GET /v1/ping and POST /v1/heartbeats . \n The minimal heartbeat \n Copy curl 'https://eu.ingest.agentping.io/v1/ping?key=ping_eu_018f3a2b9c1d7e8fa4b9c2d7e8f1a3b6&agent=daily-summary&status=ok'\n\
          \ Response is OK\\n . The run lands in your dashboard within a second. \n Adding"
  /v1/runs:
    get:
      operationId: get_v1_runs
      tags:
      - Runs
      summary: List runs newest-first.
      x-source: https://agentping.io/docs/api/read
      parameters:
      - name: from
        in: query
        required: false
        schema:
          type: string
        description: ISO 8601 bounds on received_at . Clamped to the retention horizon.
      - name: to
        in: query
        required: false
        schema:
          type: string
        description: ISO 8601 bounds on received_at . Clamped to the retention horizon.
      - name: status
        in: query
        required: false
        schema:
          type: string
        description: success , failed , timeout , or cancelled .
      - name: agent_id
        in: query
        required: false
        schema:
          type: string
        description: Agent external id or slug.
      - name: per_page
        in: query
        required: false
        schema:
          type: string
        description: 1 to 100, default 50.
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: From a prior next_cursor .
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1RunsResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_v1_runs
      tags:
      - Runs
      summary: Start a new run.
      description: Creates a new run record. Returns 202 Accepted on first write, 200 OK on idempotent retry, 409 Conflict if the ID exists with
        a different agent or started_at.
      x-source: https://agentping.io/docs/api/runs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1RunsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1RunsResponse'
      x-evidence:
        kind: documentation
  /v1/runs/{id}:
    get:
      operationId: get_v1_runs_id
      tags:
      - Runs
      summary: One run, in full.
      x-source: https://agentping.io/docs/api/read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1RunsIdResponse'
      x-evidence:
        kind: documentation
  /v1/runs/{id}/evaluation:
    get:
      operationId: get_v1_runs_id_evaluation
      tags:
      - Runs
      summary: The run's evaluation in the public shape, with internal stages collapsed to a single evaluation type.
      x-source: https://agentping.io/docs/api/read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1RunsIdEvaluationResponse'
      x-evidence:
        kind: documentation
  /v1/runs/{id}/events:
    get:
      operationId: get_v1_runs_id_events
      tags:
      - Runs
      summary: The run's events in timestamp order (up to 1000).
      x-source: https://agentping.io/docs/api/read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetV1RunsIdEventsResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_v1_runs_id_events
      tags:
      - Runs
      summary: Append one or more events to an in-flight run.
      description: Posts a batch of events atomically. Returns 202 Accepted with batch summary.
      x-source: https://agentping.io/docs/api/runs
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1RunsIdEventsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostV1RunsIdEventsResponse'
      x-evidence:
        kind: documentation
  /v1/runs/{id}/events/{eventid}/payload:
    get:
      operationId: get_v1_runs_id_events_eventid_payload
      tags:
      - Runs
      summary: The full event payload, fetched from the payload store when one exists, otherwise the inline copy.
      x-source: https://agentping.io/docs/api/read
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: eventid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /v1/runs/{id}/finish:
    post:
      operationId: post_v1_runs_id_finish
      tags:
      - Runs
      summary: Close out a run with a terminal status.
      description: Finishes a run. Returns 202 Accepted on first write, 200 OK on idempotent retry.
      x-source: https://agentping.io/docs/api/runs
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1RunsIdFinishRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    PostV1Request:
      type: object
      properties:
        id:
          type: string
        agent:
          type: string
        started_at:
          type: string
          format: date-time
        customer_id:
          type: string
        feature:
          type: string
    PostV1Response:
      type: object
      properties:
        id:
          type: string
        agent:
          type: string
        started_at:
          type: string
          format: date-time
        received_at:
          type: string
          format: date-time
        status:
          type: string
    GetV1AgentsResponse:
      type: object
      properties:
        data:
          type: array
          description: List of agents.
    PostV1HeartbeatsResponse:
      type: object
      properties:
        error:
          type: string
          description: Stable machine‑readable code.
        message:
          type: string
          description: Human‑readable explanation.
        field:
          type: string
          description: Present when tied to a specific request field.
    PostV1PingRequest:
      type: object
      properties:
        id:
          type: string
        agent:
          type: string
        status:
          type: string
        started_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
        cost_usd:
          type: number
        metadata:
          type: object
          properties:
            customers_processed:
              type: integer
            shard:
              type: string
    GetV1RunsResponse:
      type: object
      properties:
        data:
          type: array
          description: Array of run summaries.
        next_cursor:
          type: string
          description: Opaque cursor for pagination.
        retention_horizon:
          type: string
          description: Oldest timestamp you can read.
    PostV1RunsRequest:
      type: object
      properties:
        id:
          type: string
          description: Client-generated. Format run_<region>_<32 hex> . See Identifiers .
        agent:
          type: string
          description: Agent slug. New agents are auto-created on first appearance.
        started_at:
          type: string
          description: Client clock, millisecond precision. ISO 8601, UTC.
        customer_id:
          type: string
          description: Used for per-customer cost attribution.
        feature:
          type: string
          description: Free-form feature label, indexed for filters.
        metadata:
          type: object
          description: Flat key/value JSON. Paid feature, limits below.
        goal:
          type: string
          description: What the run is supposed to achieve.
        idle_timeout_seconds:
          type: integer
          description: 60–86400. Finish the run automatically if no event arrives for this long.
        idle_timeout_status:
          type: string
          description: 'What the idle sweep finishes the run with: success , failed , timeout , cancelled . Defaults to timeout.'
        version:
          type: string
          description: The agent build or prompt version that produced the run, up to 64 characters.
      required:
      - id
      - agent
      - started_at
    PostV1RunsResponse:
      type: object
      properties:
        id:
          type: string
          description: Run identifier.
        agent:
          type: string
          description: Agent slug.
        started_at:
          type: string
          description: Timestamp when run started.
        received_at:
          type: string
          description: Timestamp when request was received.
        status:
          type: string
          description: Current status, e.g., running.
    GetV1RunsIdResponse:
      type: object
      properties:
        id:
          type: string
        agent:
          type: string
        status:
          type: string
        goal:
          type: string
        customer_id:
          type: string
        feature:
          type: string
        started_at:
          type: string
        finished_at:
          type: string
        duration_ms:
          type: integer
        cost_usd:
          type: number
        total_input_tokens:
          type: integer
        total_output_tokens:
          type: integer
        step_count:
          type: integer
        error_count:
          type: integer
    GetV1RunsIdEvaluationResponse:
      type: object
      properties:
        data:
          type: object
          description: Evaluation object.
    GetV1RunsIdEventsResponse:
      type: object
      properties:
        data:
          type: array
          description: List of event objects.
    PostV1RunsIdEventsRequest:
      type: object
      properties:
        events:
          type: array
          description: Up to 50 per batch.
        events[].external_id:
          type: string
          description: Client-generated. Format evt_<region>_<32 hex>. Also accepted as id.
        events[].type:
          type: string
          description: llm_call , log , tool_call , or custom.
        events[].ts:
          type: string
          description: Client clock. ISO 8601, UTC.
        events[].turn:
          type: integer
          description: Which exchange of a conversation this belongs to.
        events[].data:
          type: object
          description: Payload.
      required:
      - events
      - events[].external_id
      - events[].type
      - events[].ts
      - events[].data
    PostV1RunsIdEventsResponse:
      type: object
      properties:
        accepted:
          type: integer
          description: Number of events accepted.
        duplicates:
          type: integer
          description: Number of events dropped due to duplicate ids.
    PostV1RunsIdFinishRequest:
      type: object
      properties:
        status:
          type: string
          description: success , failed , timeout , or cancelled.
        finished_at:
          type: string
          description: Client clock. ISO 8601, UTC.
        output:
          type: object
          description: Run result, arbitrary JSON.
        scores:
          type: object
          description: Self-reported scores keyed by metric. Numeric or boolean.
      required:
      - status
      - finished_at
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Agents
- name: Api
- name: Heartbeats
- name: Ping
- name: Runs