---
title: "Report a backup run"
method: POST
path: "/backup-runs"
tags: ["backup-runs"]
---

# Report a backup run

`POST /backup-runs`

## Request

- Base URL: `https://api.cogram.com/v1`
- URL: `https://api.cogram.com/v1/backup-runs`
- Auth: HTTP bearer

Record that a backup run started or finished.

Report `started` when a run begins and `finished` with a `status` when it
ends. A `finished` run with `status: success` clears any outstanding
stale-backup alert, so the next outage produces a fresh notification.

## Request body

- BackupRunCreateV1: One backup lifecycle event, reported by the connector.
  - `event` 'started' | 'finished', required: Lifecycle point a connector reports.
  - `schedule_interval_hours` integer, required: The connector's configured interval between runs. Cogram measures backup health against this rather than a server-side setting, because only the connector knows its own schedule.
  - `status` 'success' | 'failed': Outcome of a finished run. Absent on ``started`` events.
  - `projects_synced` integer, nullable: Projects filed by this run. Zero is a healthy result — a run with no changed projects exports nothing.
  - `error` string, nullable: Failure detail. Only meaningful when `status` is `failed`.

## Response `201`

Successful Response

- BackupRunV1: A recorded backup lifecycle event.
  - `id` string, required
  - `event` 'started' | 'finished', required: Lifecycle point a connector reports.
  - `status` 'success' | 'failed', required: Outcome of a finished run. Absent on ``started`` events.
  - `schedule_interval_hours` integer, required
  - `projects_synced` integer, nullable, required
  - `error` string, nullable, required
  - `created_at` string, date-time, required

## Other responses

- `401`: Unauthorized
- `404`: Not found
- `422`: Validation error
- `429`: Rate limit exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/cogram/apis/cogram-api.md) · [All operations](https://skmtc.dev/cogram/apis/cogram-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cogram/apis/cogram-api/revisions/5a3c9c40fca5?raw)