Report Run Web Interface

A run/read/delete interface for stored report runs - the results of executed report configs

A report run is one execution of a report config over a concrete time range; its stored result is the report — the user-facing artifact the FE renders and exports. Every run embeds a snapshot of the config it was executed with, so results stay self-contained after the report config is edited or deleted.

Storage is bounded: when the reports database reaches its size limit, the oldest terminal runs are evicted regardless of which config owns them, so a run can disappear before its config’s retention would remove it. Eviction keeps each config’s newest run and any pending/running run. Retention and eviction are both best-effort, so a config may end up keeping fewer runs than its retention.max_runs.

Fields

• run_id — server-generated UUID, read-only
• config_id — the owning report config; persists after the config is deleted
• name — the config name, taken from the embedded snapshot; omitted in the single-run response
• status — pending / running / completed / truncated / failed. truncated is a terminal success like completed, but the result was cut at the last complete row because it grew past the configured size limit
• origin — scheduled / manual
• from_sec / to_sec — the covered time range (unix seconds)
• started_at_sec — omitted while pending
• finished_at_sec — omitted while pending/running
• row_count — the number of stored rows; omitted unless completed/truncated
• error — the ClickHouse/timeout error; omitted unless failed. Report run exceeded the allowed time on the run timeout, Execution time exceeded the allowed limit when ClickHouse aborted the query on its own execution-time limit, Interrupted by a service restart when the daemon restarted mid-run
• config_snapshot — JSON of the config at the moment the run was created; single-run responses only
• result — JSON in the table endpoint response format minus state (custom_data when present, columns, page); present for completed/truncated; single-run responses only

API

• Get all report runs, newest first (includes runs of deleted report configs):

  • Path: /api/chf/report_runs

  • Method: GET

  • Arguments:

    • config_id (optional, UUID) — restrict the list to the run history of one report config

  • Response:

    {
        "message": "Success",
        "data": [
            {
                "run_id": "9f2c4b81-d7e6-a2f0-c3b5-d8e1a4f7c0b3",
                "config_id": "77ab19c2-f04d-5be6-a8c3-1d90e2f45a11",
                "name": "daily-bittorrent",
                "status": "completed",
                "origin": "scheduled",
                "from_sec": 1785110400,
                "to_sec": 1785196800,
                "started_at_sec": 1785196810,
                "finished_at_sec": 1785196812,
                "row_count": 37
            },
            {
                "run_id": "4e0f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
                "config_id": "77ab19c2-f04d-5be6-a8c3-1d90e2f45a11",
                "name": "daily-bittorrent",
                "status": "failed",
                "origin": "scheduled",
                "from_sec": 1785024000,
                "to_sec": 1785110400,
                "started_at_sec": 1785110410,
                "finished_at_sec": 1785110530,
                "error": "query timeout after 120 seconds"
            }
        ]
    }

• Get the full run with given run_id — metadata + config snapshot + result:

  • Path: /api/chf/report_runs/{run_id}

  • Method: GET

  • Response:

    {
        "message": "Success",
        "data": {
            "run_id": "9f2c4b81-d7e6-a2f0-c3b5-d8e1a4f7c0b3",
            "config_id": "77ab19c2-f04d-5be6-a8c3-1d90e2f45a11",
            "status": "completed",
            "origin": "scheduled",
            "from_sec": 1785110400,
            "to_sec": 1785196800,
            "started_at_sec": 1785196810,
            "finished_at_sec": 1785196812,
            "row_count": 37,
            "config_snapshot": {
                "name": "daily-bittorrent",
                "type": "table",
                "source": "top_applications",
                "query": {"filter_clause": "application = 'BitTorrent'", "limit": 100},
                "query_structured": {"filter_clause": []},
                "range_sec": 86400,
                "keep_empty_runs": true,
                "enabled": true
            },
            "result": {
                "columns": [{"name": "application", "type": "string"}],
                "page": [{"application": "BitTorrent", "update_total_bytes": 56658058754}]
            }
        }
    }

• Run a report config manually — the run starts at once if a slot is free, otherwise it waits as pending:

  • Path: /api/chf/report_runs

  • Method: POST

  • Body:

    • config_id (mandatory, UUID) — the report config to run

    • from_sec / to_sec (optional, unix seconds, always together, from_sec < to_sec) — an explicit window

    • range_sec (optional, > 0) — the window [now - range_sec, now], now being the time of the request; ignored when from_sec / to_sec are given

    • neither — the window [now - config.range_sec, now]

      {
          "config_id": "77ab19c2-f04d-5be6-a8c3-1d90e2f45a11",
          "range_sec": 86400
      }

  • Response: the run as it stands right after the start attempt (running or pending)

    {
        "message": "Success",
        "data": {
            "run_id": "9f2c4b81-d7e6-a2f0-c3b5-d8e1a4f7c0b3",
            "config_id": "77ab19c2-f04d-5be6-a8c3-1d90e2f45a11",
            "name": "daily-bittorrent",
            "status": "running",
            "origin": "manual",
            "from_sec": 1785024000,
            "to_sec": 1785110400,
            "started_at_sec": 1785110400
        }
    }

• Delete the run with given run_id:

  • Path: /api/chf/report_runs/{run_id}

  • Method: DELETE

  • Response:

    {
        "message": "The report run has been deleted",
        "data": null
    }

• Delete stored runs:

  • Path: /api/chf/report_runs

  • Method: DELETE

  • Arguments:

    • config_id (optional, UUID) — delete only the stored runs of one report config

  • Response without config_id:

    {
        "message": "All report runs have been deleted",
        "data": null
    }

  • Response with config_id:

    {
        "message": "All runs of the report config have been deleted",
        "data": null
    }

Back to Clickhouse Facade