Plan runs V5 (beta)

Check whether each scheduled run of a plan happened on time.

For every promised time (run) of a plan, see whether it ran, was skipped, was missed or is still upcoming. It uses the same basis as the "Plan runs" view on screen. This path is available only to accounts where multiple plans are open (otherwise 404 PLAN_NOT_FOUND).

Endpoints

  • GET /v5/api/plans/{plan_id}/runs Runs (newest first) with counts per state

Run list

Query: state (ran, skipped, missed, upcoming), from and to (scheduled time range, ISO 8601 or YYYY-MM-DD), cursor and limit. The default range is the last 14 days and a range is at most 31 days. Newest first, with upcoming runs at the front. next_cursor is the scheduled time (epoch seconds); pass it as cursor to get earlier runs. counts covers the whole range regardless of filtering.

Example request 
curl 'https://www.hashscraper.com/v5/api/plans/512/runs?from=2026-09-01&to=2026-10-04&state=skipped&limit=50' \
  -H 'Authorization: Bearer YOUR_API_KEY'
Example response 200 
{
  "result": "success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "count": 5,
  "next_cursor": null,
  "data": {
    "plan_id": "512",
    "source": "ledger",
    "from": "2026-09-01T00:00:00+09:00",
    "to": "2026-10-04T23:59:59+09:00",
    "counts": {
      "ran": 1,
      "skipped": 1,
      "missed": 1,
      "upcoming": 2
    },
    "runs": [
      {
        "scheduled_at": "2026-10-12T09:00:00+09:00",
        "state": "upcoming",
        "reason": null,
        "dataset_id": null
      },
      {
        "scheduled_at": "2026-10-05T09:00:00+09:00",
        "state": "upcoming",
        "reason": null,
        "dataset_id": null
      },
      {
        "scheduled_at": "2026-09-28T09:00:00+09:00",
        "state": "ran",
        "reason": null,
        "dataset_id": 239758028
      },
      {
        "scheduled_at": "2026-09-21T09:00:00+09:00",
        "state": "skipped",
        "reason": "insufficient_credit",
        "dataset_id": null
      },
      {
        "scheduled_at": "2026-09-14T09:00:00+09:00",
        "state": "missed",
        "reason": "expired",
        "dataset_id": null
      }
    ]
  }
}

States and reasons

statereasonMeaning
ran—It ran. dataset_id is that collection.
skippedalready_runningSkipped because the previous collection was still running.
skippedinsufficient_creditSkipped because of insufficient credits.
skippedticket_expired, no_service_ticket, service_ticket_invalidSkipped because of a ticket problem.
missedexpiredClosed because it was too late.
missednot_recordedThe runner did not record it.
upcoming—Not yet. Includes future runs and runs that just passed and are waiting for a result (about 10 minutes).

Basis of the judgment: source

source in the response tells you what the plan was judged on.

sourceMeaning
ledgerA plan run by the plan runner. Read from the run records. A past scheduled time without a record is missed.
screenPlan 1 running the old way. Judged by matching dataset times. There is no basis for why a run was skipped, so skipped never appears.
noneA plan without runs (its conditions are set separately but the runner is not running it yet). runs is an empty array.

Limits to know

  • The evidence for a run skipped because it overlapped a previous collection is kept for only 2 days. After two days the same run shows as missed instead of skipped.
  • A run skipped for maintenance leaves no evidence and shows as missed (expired).
  • Only runs after the plan was turned on or last edited are counted. The time it was off cannot be known.

Related guides