Ingest API Schema

Documentation for sending custom pipeline metrics to RunWatch's ingestion API

Overview

The RunWatch Ingest API allows you to send pipeline and job metrics directly from any CI/CD platform or custom script. This is useful for:

Integrating CI/CD platforms that don't have official reporters
Building custom reporting solutions
Sending metrics from scripts or automation tools
Testing and debugging metric collection

Note: For GitHub Actions and GitLab CI/CD, we recommend using the official reporter actions/components. See the Reporter Actions documentation for details.

Endpoint

POST https://api.runwatch.io/functions/v1/ingest

The ingestion endpoint accepts POST requests with JSON payloads containing pipeline metrics.

Authentication

Authenticate requests using your organization's API key. You can create and manage API keys in the Access Keys section of the dashboard.

Headers:

X-API-Key: your_api_key_here

Request Schema

The request body must be a JSON object matching the following schema:

{
  "provider": "github" | "gitlab" | "bitbucket" | "circleci" | "other",
  "repository": "owner/repo-name",
  "pipeline_id": "string (optional)",
  "pipeline_name": "string",
  "run_id": number,
  "run_attempt": number,
  "run_name": "string (optional)",
  "run_url": "string (optional)",
  "status": "success" | "failure" | "cancelled" | "running" | 
             "queued" | "pending" | "skipped" | "timed_out",
  "mode": "inline" | "external",
  "compute_seconds": number (optional),
  "duration_seconds": number (optional),
  "started_at": "ISO 8601 timestamp",
  "completed_at": "ISO 8601 timestamp (optional)",
  "triggered_by": "string",
  "actor": "string",
  "branch": "string (optional)",
  "jobs": [
    {
      "name": "string",
      "job_id": "string (optional)",
      "job_url": "string (optional)",
      "status": "success" | "failure" | "cancelled" | "running" | 
                "queued" | "pending" | "skipped" | "timed_out",
      "duration_seconds": number (optional),
      "started_at": "ISO 8601 timestamp (optional)",
      "completed_at": "ISO 8601 timestamp (optional)"
    }
  ]
}

Field Descriptions

Pipeline/Workflow Fields

providerrequired

CI/CD platform identifier: "github", "gitlab", "bitbucket", "circleci", or "other"

repositoryrequired

Full repository name in format "owner/repo-name" (e.g., "acme/cool-project")

pipeline_namerequired

Display name of the pipeline/workflow (e.g., "CI Pipeline", "Deploy to Prod")

run_idrequired

Unique numeric identifier for this pipeline run (must be unique per pipeline)

run_attemptrequired

Attempt number for this run (starts at 1, increments on retries)

statusrequired

Current status of the pipeline run. Must be one of: "success", "failure", "cancelled", "running", "queued", "pending", "skipped", "timed_out"

started_atrequired

ISO 8601 timestamp when the pipeline run started (e.g., "2024-01-15T10:30:00Z")

triggered_byrequired

Event or source that triggered the pipeline (e.g., "push", "pull_request", "manual", "schedule")

actorrequired

User or system that triggered the pipeline (username, email, or system identifier)

pipeline_idoptional

Platform-specific pipeline/workflow identifier

run_nameoptional

Display name or title for this specific run

run_urloptional

Direct URL to view this run in the CI/CD platform's UI

modeoptional

How metrics were collected: "inline" (as part of pipeline) or "external" (separate reporting step)

compute_secondsoptional

Total compute time across all jobs (useful for cost analysis, accounts for parallel execution)

duration_secondsoptional

Total pipeline execution time in seconds. If not provided, calculated from started_at and completed_at

completed_atoptional

ISO 8601 timestamp when the pipeline run completed. Required for completed runs

branchoptional

Git branch name that triggered this run

Job Fields

namerequired

Display name of the job (e.g., "build", "test", "deploy")

statusrequired

Current status of the job. Same values as pipeline status

job_idoptional

Platform-specific job identifier

job_urloptional

Direct URL to view this job in the CI/CD platform's UI

duration_secondsoptional

Job execution time in seconds. If not provided, calculated from started_at and completed_at

started_atoptional

ISO 8601 timestamp when the job started

completed_atoptional

ISO 8601 timestamp when the job completed

Example Request

curl -X POST https://api.runwatch.io/functions/v1/ingest \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "provider": "github",
    "repository": "acme/cool-project",
    "pipeline_name": "CI Pipeline",
    "run_id": 789012345,
    "run_attempt": 1,
    "run_name": "Fix login bug",
    "run_url": "https://github.com/acme/cool-project/actions/runs/789012345",
    "status": "success",
    "mode": "inline",
    "compute_seconds": 245,
    "duration_seconds": 312,
    "started_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T10:35:12Z",
    "triggered_by": "push",
    "actor": "octocat",
    "branch": "main",
    "jobs": [
      {
        "name": "build",
        "job_id": "456789",
        "job_url": "https://github.com/acme/cool-project/actions/runs/789012345/job/456789",
        "status": "success",
        "duration_seconds": 120,
        "started_at": "2024-01-15T10:30:05Z",
        "completed_at": "2024-01-15T10:32:05Z"
      },
      {
        "name": "test",
        "job_id": "456790",
        "job_url": "https://github.com/acme/cool-project/actions/runs/789012345/job/456790",
        "status": "success",
        "duration_seconds": 125,
        "started_at": "2024-01-15T10:32:10Z",
        "completed_at": "2024-01-15T10:34:15Z"
      }
    ]
  }'

Response

Success (200):

{
  "success": true,
  "pipeline_run_id": "uuid"
}

Error (4xx/5xx):

{
  "error": "Error message description"
}

Error Codes

401

Unauthorized - Invalid or missing API key

400

Bad Request - Invalid request format or missing required fields

402

Payment Required - Plan limits exceeded (repository or run limits)

500

Internal Server Error - Server-side error processing the request

CORS

The ingestion API supports CORS (Cross-Origin Resource Sharing) for browser-based integrations. The API accepts requests from any origin and includes appropriate CORS headers in responses.