MetriBeacon
Menu

POST Calculate a report

/api/v1/workspaces/{id}/reporting/queries

Creates or reuses a bounded analysis job. Periods support up to 365 days; hourly grouping supports 14 days. Group members are frozen at calculation start. Interactive results expire after 24 hours. Inspect the returned analysis job until it completes.

On this page

Access and permissions

Creates or reuses a bounded analysis job. Periods support up to 365 days; hourly grouping supports 14 days. Group members are frozen at calculation start. Interactive results expire after 24 hours. Inspect the returned analysis job until it completes.

Browser session: __Host-mb_session cookie.

Machine management credentials in Authorization: Bearer. Check the permissions (scopes) required by the operation.

Parameters and headers

FieldLocationType and limitsRequiredMeaning
idPathstring; {"format":"uuid"}YesResource ID in this workspace

Request body

FieldType and limitsRequiredMeaning
$ReportingQueryYes—
$.adjustedbooleanNo—
$.chart_sourcesarray<string; {"maxLength":200}>; {"maxItems":8}No—
$.chart_sources[]string; {"maxLength":200}Yes—
$.filtersReportingFiltersYes—
$.filters.channelstring; {"enum":["","email","telegram","discord","slack","ntfy","webhook","webpush"]}No—
$.filters.filesystemstring; {"maxLength":512}No—
$.filters.group_idsarray<string; {"format":"uuid"}>; {"maxItems":1000}No—
$.filters.group_ids[]string; {"format":"uuid"}Yes—
$.filters.location_idsarray<string; {"format":"uuid"}>; {"maxItems":1000}No—
$.filters.location_ids[]string; {"format":"uuid"}Yes—
$.filters.monitor_idsarray<string; {"format":"uuid"}>; {"maxItems":1000}No—
$.filters.monitor_ids[]string; {"format":"uuid"}Yes—
$.filters.resourcestring; {"enum":["","cpu","memory","filesystem","disk","network"]}No—
$.filters.severitystring; {"enum":["","info","warning","critical"]}No—
$.filters.typesarray<string; {"maxLength":32}>; {"maxItems":1000}No—
$.filters.types[]string; {"maxLength":32}Yes—
$.fromstring; {"format":"date-time"}Yes—
$.granularitystring; {"enum":["hour","day","week","month"]}Yes—
$.languagestring; {"enum":["en","de"]}No—
$.sectionsarray<string; {"enum":["overview","availability","incidents","mttr","mtta","response","maintenance","notifications","certificates","jobs","resources"]}>; {"maxItems":11,"minItems":1}Yes—
$.sections[]string; {"enum":["overview","availability","incidents","mttr","mtta","response","maintenance","notifications","certificates","jobs","resources"]}Yes—
$.timezonestring; {"maxLength":64}Yes—
$.tostring; {"format":"date-time"}Yes—
$.versioninteger; {"const":1}No—

Responses

application/json

FieldType and limitsRequiredMeaning
$object; {"additionalProperties":false}Yes—
$.idstring; {"format":"uuid"}Yes—
Stable error codes
invalid_session

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
Stable error codes
csrf
forbidden
insufficient_scope
owner_required

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
Stable error codes
not_found

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
Stable error codes
idempotency_conflict
job_not_active
job_not_ready
revision_conflict

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
Stable error codes
invalid_idempotency_key
invalid_report
invalid_slo

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
Stable error codes
alarm_limit
analysis_capacity
report_limit
slo_limit

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—
Stable error codes
unavailable

application/problem+json

FieldType and limitsRequiredMeaning
$ProblemYes—
$.codestringYesStable machine-readable error code
$.detailstringYesShort localized explanation without internal error details
$.instancestringYesUnique relative identifier /api/v1/requests/{request_id}; not a retrievable resource
$.messagestringYesTemporarily identical to detail for existing clients
$.message_keystringYesStable translation key for changing the displayed language without another request
$.message_paramsobject; {"additionalProperties":true}YesNamed, safely rendered message parameters; never arbitrary HTML
$.request_idstring; {"pattern":"^[0-9a-f]{32}$"}YesServer-generated diagnostic identifier. It contains no login token or credential.
$.statusinteger; {"maximum":599,"minimum":400}Yes—
$.titlestringYesLocalized HTTP status title
$.typestring; {"const":"about:blank"}Yes—

Retries and asynchronous work

This change does not have a general retry guarantee. If the response is unclear, read the affected resource before trying again. Follow Retry-After waiting times and request new sign-in or action codes when they expire.

HTTP 202 means the background job was accepted. Use the returned job ID to check its status. Download results when the job is complete, or inspect its error or cancellation status.

Request examples

Replace demo IDs, timestamps and placeholders with your own values. For a retry, keep the same IDs, time and content. These examples do not run requests on this page.

Keep login links, codes, cookies and keys private. Do not print them in logs or share them in support requests.

shell
curl --silent --show-error --request POST --header @"$HOME/.config/metribeacon/headers.txt" --header "Content-Type: application/json" --data '{"version":1,"sections":["availability"],"timezone":"Europe/Berlin","language":"en","granularity":"day","filters":{"monitor_ids":[],"types":[],"group_ids":[],"location_ids":[]},"from":"2026-10-01T00:00:00Z","to":"2026-10-08T00:00:00Z"}' 'https://metribeacon.com/api/v1/workspaces/00000000-0000-4000-8000-000000000001/reporting/queries'
python
import json
from pathlib import Path
from urllib.request import Request, HTTPRedirectHandler, build_opener
headers = json.loads((Path.home()/".config/metribeacon/headers.json").read_text())
class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, request, fp, code, message, headers, target): return None
headers["Content-Type"]="application/json"
request=Request('https://metribeacon.com/api/v1/workspaces/00000000-0000-4000-8000-000000000001/reporting/queries',data=json.dumps({'version': 1, 'sections': ['availability'], 'timezone': 'Europe/Berlin', 'language': 'en', 'granularity': 'day', 'filters': {'monitor_ids': [], 'types': [], 'group_ids': [], 'location_ids': []}, 'from': '2026-10-01T00:00:00Z', 'to': '2026-10-08T00:00:00Z'}).encode(),headers=headers,method='POST')
with build_opener(NoRedirect).open(request,timeout=60) as response:
    print(response.status)
javascript
import {readFile} from "node:fs/promises";
import {homedir} from "node:os";
import {join} from "node:path";
const headers=JSON.parse(await readFile(join(homedir(),".config/metribeacon/headers.json"),"utf8"));
headers["Content-Type"]="application/json";
const response=await fetch("https://metribeacon.com/api/v1/workspaces/00000000-0000-4000-8000-000000000001/reporting/queries",{method:"POST",headers,redirect:"error",signal:AbortSignal.timeout(60000),body:JSON.stringify({"version":1,"sections":["availability"],"timezone":"Europe/Berlin","language":"en","granularity":"day","filters":{"monitor_ids":[],"types":[],"group_ids":[],"location_ids":[]},"from":"2026-10-01T00:00:00Z","to":"2026-10-08T00:00:00Z"})});
console.log(response.status);await response.body?.cancel();
go
package main
import("encoding/json";"fmt";"net/http";"os";"path/filepath";"time";"strings")
func main(){home,e:=os.UserHomeDir();if e!=nil{return};raw,e:=os.ReadFile(filepath.Join(home,".config/metribeacon/headers.json"));if e!=nil{return};var headers map[string]string;if json.Unmarshal(raw,&headers)!=nil{return};req,e:=http.NewRequest("POST","https://metribeacon.com/api/v1/workspaces/00000000-0000-4000-8000-000000000001/reporting/queries",strings.NewReader("{\"version\":1,\"sections\":[\"availability\"],\"timezone\":\"Europe/Berlin\",\"language\":\"en\",\"granularity\":\"day\",\"filters\":{\"monitor_ids\":[],\"types\":[],\"group_ids\":[],\"location_ids\":[]},\"from\":\"2026-10-01T00:00:00Z\",\"to\":\"2026-10-08T00:00:00Z\"}"));if e!=nil{return};for k,v:=range headers{req.Header.Set(k,v)};req.Header.Set("Content-Type","application/json");client:=&http.Client{Timeout:60*time.Second,CheckRedirect:func(*http.Request,[]*http.Request)error{return http.ErrUseLastResponse}};res,e:=client.Do(req);if e!=nil{return};defer res.Body.Close();fmt.Println(res.StatusCode)}
  • HTTP API, OAuth and MCP

    Find the user API endpoints, their permissions, fields, examples and response formats.

  • GET List report sources

    Lists report sections and authorized monitor, group, location and filesystem choices. Viewer access is sufficient; machine clients need telemetry:read.

  • GET List report schedules

    Workspace SLOs use the aggregate availability series of HTTP, TCP, UDP, DNS, TLS, ping, service, domain and browser monitors. Unknown and unobserved time remain explicit; satisfaction is only proven by the lower availability bound. Ten SLOs and three report schedules are allowed per workspace. Calendar reports are immutable for 90 days. Email requires explicit owner opt-in and a verified destination, and shares the existing notification quota. Asynchronous jobs share four global slots and one per owner, can be cancelled and cannot cross workspace boundaries. Choose daily, weekly or monthly reports and a dispatch time (HH:MM) in an IANA timezone. Reports cover the previous local calendar day, Monday–Sunday week or month. Processing starts at that time; delivery may be later. During daylight-saving changes, a missing time moves to the next valid minute and a repeated time runs only once. Manual generation uses the last closed period regardless of the dispatch time.

  • POST Create a report schedule

    Workspace SLOs use the aggregate availability series of HTTP, TCP, UDP, DNS, TLS, ping, service, domain and browser monitors. Unknown and unobserved time remain explicit; satisfaction is only proven by the lower availability bound. Ten SLOs and three report schedules are allowed per workspace. Calendar reports are immutable for 90 days. Email requires explicit owner opt-in and a verified destination, and shares the existing notification quota. Asynchronous jobs share four global slots and one per owner, can be cancelled and cannot cross workspace boundaries. Choose daily, weekly or monthly reports and a dispatch time (HH:MM) in an IANA timezone. Reports cover the previous local calendar day, Monday–Sunday week or month. Processing starts at that time; delivery may be later. During daylight-saving changes, a missing time moves to the next valid minute and a repeated time runs only once. Manual generation uses the last closed period regardless of the dispatch time.