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
| Field | Location | Type and limits | Required | Meaning |
|---|---|---|---|---|
| id | Path | string; {"format":"uuid"} | Yes | Resource ID in this workspace |
Request body
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | ReportingQuery | Yes | — |
| $.adjusted | boolean | No | — |
| $.chart_sources | array<string; {"maxLength":200}>; {"maxItems":8} | No | — |
| $.chart_sources[] | string; {"maxLength":200} | Yes | — |
| $.filters | ReportingFilters | Yes | — |
| $.filters.channel | string; {"enum":["","email","telegram","discord","slack","ntfy","webhook","webpush"]} | No | — |
| $.filters.filesystem | string; {"maxLength":512} | No | — |
| $.filters.group_ids | array<string; {"format":"uuid"}>; {"maxItems":1000} | No | — |
| $.filters.group_ids[] | string; {"format":"uuid"} | Yes | — |
| $.filters.location_ids | array<string; {"format":"uuid"}>; {"maxItems":1000} | No | — |
| $.filters.location_ids[] | string; {"format":"uuid"} | Yes | — |
| $.filters.monitor_ids | array<string; {"format":"uuid"}>; {"maxItems":1000} | No | — |
| $.filters.monitor_ids[] | string; {"format":"uuid"} | Yes | — |
| $.filters.resource | string; {"enum":["","cpu","memory","filesystem","disk","network"]} | No | — |
| $.filters.severity | string; {"enum":["","info","warning","critical"]} | No | — |
| $.filters.types | array<string; {"maxLength":32}>; {"maxItems":1000} | No | — |
| $.filters.types[] | string; {"maxLength":32} | Yes | — |
| $.from | string; {"format":"date-time"} | Yes | — |
| $.granularity | string; {"enum":["hour","day","week","month"]} | Yes | — |
| $.language | string; {"enum":["en","de"]} | No | — |
| $.sections | array<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 | — |
| $.timezone | string; {"maxLength":64} | Yes | — |
| $.to | string; {"format":"date-time"} | Yes | — |
| $.version | integer; {"const":1} | No | — |
Responses
application/json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | object; {"additionalProperties":false} | Yes | — |
| $.id | string; {"format":"uuid"} | Yes | — |
| Stable error codes |
|---|
| invalid_session |
application/problem+json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | Problem | Yes | — |
| $.code | string | Yes | Stable machine-readable error code |
| $.detail | string | Yes | Short localized explanation without internal error details |
| $.instance | string | Yes | Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource |
| $.message | string | Yes | Temporarily identical to detail for existing clients |
| $.message_key | string | Yes | Stable translation key for changing the displayed language without another request |
| $.message_params | object; {"additionalProperties":true} | Yes | Named, safely rendered message parameters; never arbitrary HTML |
| $.request_id | string; {"pattern":"^[0-9a-f]{32}$"} | Yes | Server-generated diagnostic identifier. It contains no login token or credential. |
| $.status | integer; {"maximum":599,"minimum":400} | Yes | — |
| $.title | string | Yes | Localized HTTP status title |
| $.type | string; {"const":"about:blank"} | Yes | — |
| Stable error codes |
|---|
| csrf |
| forbidden |
| insufficient_scope |
| owner_required |
application/problem+json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | Problem | Yes | — |
| $.code | string | Yes | Stable machine-readable error code |
| $.detail | string | Yes | Short localized explanation without internal error details |
| $.instance | string | Yes | Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource |
| $.message | string | Yes | Temporarily identical to detail for existing clients |
| $.message_key | string | Yes | Stable translation key for changing the displayed language without another request |
| $.message_params | object; {"additionalProperties":true} | Yes | Named, safely rendered message parameters; never arbitrary HTML |
| $.request_id | string; {"pattern":"^[0-9a-f]{32}$"} | Yes | Server-generated diagnostic identifier. It contains no login token or credential. |
| $.status | integer; {"maximum":599,"minimum":400} | Yes | — |
| $.title | string | Yes | Localized HTTP status title |
| $.type | string; {"const":"about:blank"} | Yes | — |
| Stable error codes |
|---|
| not_found |
application/problem+json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | Problem | Yes | — |
| $.code | string | Yes | Stable machine-readable error code |
| $.detail | string | Yes | Short localized explanation without internal error details |
| $.instance | string | Yes | Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource |
| $.message | string | Yes | Temporarily identical to detail for existing clients |
| $.message_key | string | Yes | Stable translation key for changing the displayed language without another request |
| $.message_params | object; {"additionalProperties":true} | Yes | Named, safely rendered message parameters; never arbitrary HTML |
| $.request_id | string; {"pattern":"^[0-9a-f]{32}$"} | Yes | Server-generated diagnostic identifier. It contains no login token or credential. |
| $.status | integer; {"maximum":599,"minimum":400} | Yes | — |
| $.title | string | Yes | Localized HTTP status title |
| $.type | string; {"const":"about:blank"} | Yes | — |
| Stable error codes |
|---|
| idempotency_conflict |
| job_not_active |
| job_not_ready |
| revision_conflict |
application/problem+json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | Problem | Yes | — |
| $.code | string | Yes | Stable machine-readable error code |
| $.detail | string | Yes | Short localized explanation without internal error details |
| $.instance | string | Yes | Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource |
| $.message | string | Yes | Temporarily identical to detail for existing clients |
| $.message_key | string | Yes | Stable translation key for changing the displayed language without another request |
| $.message_params | object; {"additionalProperties":true} | Yes | Named, safely rendered message parameters; never arbitrary HTML |
| $.request_id | string; {"pattern":"^[0-9a-f]{32}$"} | Yes | Server-generated diagnostic identifier. It contains no login token or credential. |
| $.status | integer; {"maximum":599,"minimum":400} | Yes | — |
| $.title | string | Yes | Localized HTTP status title |
| $.type | string; {"const":"about:blank"} | Yes | — |
| Stable error codes |
|---|
| invalid_idempotency_key |
| invalid_report |
| invalid_slo |
application/problem+json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | Problem | Yes | — |
| $.code | string | Yes | Stable machine-readable error code |
| $.detail | string | Yes | Short localized explanation without internal error details |
| $.instance | string | Yes | Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource |
| $.message | string | Yes | Temporarily identical to detail for existing clients |
| $.message_key | string | Yes | Stable translation key for changing the displayed language without another request |
| $.message_params | object; {"additionalProperties":true} | Yes | Named, safely rendered message parameters; never arbitrary HTML |
| $.request_id | string; {"pattern":"^[0-9a-f]{32}$"} | Yes | Server-generated diagnostic identifier. It contains no login token or credential. |
| $.status | integer; {"maximum":599,"minimum":400} | Yes | — |
| $.title | string | Yes | Localized HTTP status title |
| $.type | string; {"const":"about:blank"} | Yes | — |
| Stable error codes |
|---|
| alarm_limit |
| analysis_capacity |
| report_limit |
| slo_limit |
application/problem+json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | Problem | Yes | — |
| $.code | string | Yes | Stable machine-readable error code |
| $.detail | string | Yes | Short localized explanation without internal error details |
| $.instance | string | Yes | Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource |
| $.message | string | Yes | Temporarily identical to detail for existing clients |
| $.message_key | string | Yes | Stable translation key for changing the displayed language without another request |
| $.message_params | object; {"additionalProperties":true} | Yes | Named, safely rendered message parameters; never arbitrary HTML |
| $.request_id | string; {"pattern":"^[0-9a-f]{32}$"} | Yes | Server-generated diagnostic identifier. It contains no login token or credential. |
| $.status | integer; {"maximum":599,"minimum":400} | Yes | — |
| $.title | string | Yes | Localized HTTP status title |
| $.type | string; {"const":"about:blank"} | Yes | — |
| Stable error codes |
|---|
| unavailable |
application/problem+json
| Field | Type and limits | Required | Meaning |
|---|---|---|---|
| $ | Problem | Yes | — |
| $.code | string | Yes | Stable machine-readable error code |
| $.detail | string | Yes | Short localized explanation without internal error details |
| $.instance | string | Yes | Unique relative identifier /api/v1/requests/{request_id}; not a retrievable resource |
| $.message | string | Yes | Temporarily identical to detail for existing clients |
| $.message_key | string | Yes | Stable translation key for changing the displayed language without another request |
| $.message_params | object; {"additionalProperties":true} | Yes | Named, safely rendered message parameters; never arbitrary HTML |
| $.request_id | string; {"pattern":"^[0-9a-f]{32}$"} | Yes | Server-generated diagnostic identifier. It contains no login token or credential. |
| $.status | integer; {"maximum":599,"minimum":400} | Yes | — |
| $.title | string | Yes | Localized HTTP status title |
| $.type | string; {"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.
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'
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)
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();
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)}
Related guides
- 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.