# Create a report schedule — API reference > Creates a report schedule with cadence, recipients, report type, language, timezone and frozen report parameters. Source: https://upfour.io/docs/api/reports/create-a-report-schedule [Developers](https://upfour.io/docs/api.md)/[Reports](https://upfour.io/docs/api/reports.md) Creates a report schedule with cadence, recipients, report type, language, timezone and frozen report parameters. POST https://app.upfour.io/v1/reports/schedules scope report.write stable [Idempotency-Key supported](https://upfour.io/docs/api/idempotency.md) returns 201 ## Body The 4 fields most calls use come first; the rest are grouped below. `application/json` required 13 fields namestring (required) 1 to 200 characters without line breaks. In the app: **Name** report_typestring (required) executive_summarysummarymonitor_reportmonitorsmonitor_slaslaincident_analyticsincidentsresponse_timeresponse-timedowntime_ledgerdowntime-ledgertrends In the app: **Report** cadencestring (required) weeklymonthly In the app: **Cadence** recipientsstring (email)[] (required) 1 to 50 distinct email addresses. In the app: **Recipients** Timing4 fields day_of_weekinteger · nullable Required for weekly: 1 (Monday) to 7 (Sunday). day_of_monthinteger · nullable Required for monthly: 1 to 28. In the app: **Day of month** send_hourinteger Hour of the day, 0 to 23, in timezone. 0 when omitted. In the app: **Send at (hour)** timezonestring IANA time zone; UTC when omitted. In the app: **Timezone** Delivery3 fields formatstring Defaults to pdf. csvjsonpdfxlsx In the app: **Format** languagestring · nullable en or de (a region such as de-DE or the language name is accepted); null or empty inherits from the client, then the Company. In the app: **Report language** enabledboolean · nullable true when omitted, on update too. Scope and parameters2 fields client_iduuid · nullable Report on one client; omitted means the Company level. On update, omitting it keeps the schedule's client. In the app: **Scope to client (optional)** paramsobjectfree-form keys Frozen report parameters: preset, from and to (the window, as in the query of the report endpoints), target (SLA target in percent, above 0 up to 100) and filters (monitor, severity and search narrowing; region, tag and group filters are refused). Without a window a weekly schedule reports the last 7 days and a monthly one the previous month. ## Returns A successful request returns `201` with application/json. Response fields 1 top-level fields | Field | Type | Description | | --- | --- | --- | | `data` | ReportSchedule | | | ReportSchedule · 21 fields FieldTypeDescription `cadence` string one of`weekly` `monthly` `created_at` string (date-time) `enabled` boolean `format` string one of`csv` `json` `pdf` `xlsx` `id` uuid `language` string · nullable one of`en` `de` null when the schedule inherits. `name` string `next_run_at` string (date-time) `organization_id` uuid `params` object · nullable free-form keys The frozen report parameters; see the request. `recipients` string[] · nullable `report_type` string one of`executive_summary` `summary` `monitor_report` `monitors` `monitor_sla` `sla` `incident_analytics` `incidents` `response_time` `response-time` `downtime_ledger` `downtime-ledger` `trends` `send_hour` integer `timezone` string `updated_at` string (date-time) `client_id` uuid `created_by` uuid `day_of_month` integer `day_of_week` integer `effective_language` string one of`en` `de` The language the schedule renders in now. `last_run_at` string (date-time) | | | ## Errors Only the errors this operation can return. Every error uses the [same envelope](https://upfour.io/docs/api/responses.md). | Status | Code | Meaning | | --- | --- | --- | | 400 | [bad_request](https://upfour.io/docs/api/errors#code-bad_request) | The request is malformed or fails validation. | | 402 | [billing_action_unavailable](https://upfour.io/docs/api/errors#code-billing_action_unavailable) | The Company's billing state does not allow this action. **When:** A metered or limited action while the billing state, such as paused or without credit, blocks it; details holds the action and billing_state. **Fix:** Top up the credit or change the plan, then retry. | | 403 | [permission_denied](https://upfour.io/docs/api/errors#code-permission_denied) | The credentials do not permit this action. | | 503 | [quota_gate_unavailable](https://upfour.io/docs/api/errors#code-quota_gate_unavailable) | The limit check itself failed, so the action was not carried out. **When:** The quota service could not decide while the request ran. **Fix:** Retry in a moment; nothing was changed. | | 403 / 429 | [quota_limit_reached](https://upfour.io/docs/api/errors#code-quota_limit_reached) | A usage or inventory limit of the Company was reached. **When:** Counters and concurrency limits answer 429 with Retry-After, inventory and capacity limits answer 403; details holds purpose, limit and window. **Fix:** On 429 wait Retry-After seconds; on 403 free something up, request a higher limit where details.raise_request is true, or buy an extension. | Every call can also return `unauthorized` (401), `rate_limit_exceeded` (429) or `internal_error` (500 / 502). See [Responses and errors](https://upfour.io/docs/api/responses.md). [PreviousList report schedules](https://upfour.io/docs/api/reports/list-report-schedules.md) [NextPreview a report schedule](https://upfour.io/docs/api/reports/preview-a-report-schedule.md) ## Request ### cURL ```bash curl -s -X POST "https://app.upfour.io/v1/reports/schedules" \ -H "Authorization: Bearer $UP4_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "cadence": "weekly", "day_of_week": 1, "enabled": true, "format": "pdf", "language": "en", "name": "Weekly summary", "recipients": [ "anna@example.com" ], "report_type": "summary", "send_hour": 8, "timezone": "Europe/Berlin" }' ``` ### JavaScript ```javascript const res = await fetch("https://app.upfour.io/v1/reports/schedules", { method: "POST", headers: { Authorization: `Bearer ${process.env.UP4_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ cadence: "weekly", day_of_week: 1, enabled: true, format: "pdf", language: "en", name: "Weekly summary", recipients: ["anna@example.com"], report_type: "summary", send_hour: 8, timezone: "Europe/Berlin", }), }); console.log(res.status, await res.json()); ``` ### Python ```python import os import requests res = requests.post( "https://app.upfour.io/v1/reports/schedules", headers={"Authorization": f"Bearer {os.environ['UP4_API_KEY']}"}, json={ "cadence": "weekly", "day_of_week": 1, "enabled": True, "format": "pdf", "language": "en", "name": "Weekly summary", "recipients": ["anna@example.com"], "report_type": "summary", "send_hour": 8, "timezone": "Europe/Berlin", }, ) print(res.status_code, res.json()) ``` ### Go ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "cadence": "weekly", "day_of_week": 1, "enabled": true, "format": "pdf", "language": "en", "name": "Weekly summary", "recipients": [ "anna@example.com" ], "report_type": "summary", "send_hour": 8, "timezone": "Europe/Berlin" }`) req, _ := http.NewRequest("POST", "https://app.upfour.io/v1/reports/schedules", payload) req.Header.Set("Authorization", "Bearer "+os.Getenv("UP4_API_KEY")) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() out, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(out)) } ``` ### PHP ```php "POST", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("UP4_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => $payload, ]); $response = curl_exec($ch); echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), " ", $response, "\n"; curl_close($ch); ``` ## Response ### 201 ```json { "data": { "cadence": "weekly", "created_at": "2026-10-27T09:00:00Z", "created_by": "00000000-0000-4000-8000-000000000001", "day_of_week": 1, "effective_language": "en", "enabled": true, "format": "pdf", "id": "00000000-0000-4000-8000-000000000002", "language": "en", "name": "Weekly summary", "next_run_at": "2026-11-01T23:55:00Z", "organization_id": "00000000-0000-4000-8000-000000000003", "params": { "preset": "7d" }, "recipients": [ "anna@example.com" ], "report_type": "summary", "send_hour": 8, "timezone": "Europe/Berlin", "updated_at": "2026-10-27T09:00:00Z" } } ``` ### 400 ```json { "error": { "code": "bad_request", "message": "The request is malformed or fails validation.", "request_id": "req_…" } } ``` ### 402 ```json { "error": { "code": "billing_action_unavailable", "message": "The Company's billing state does not allow this action.", "request_id": "req_…" } } ``` ### 403 ```json { "error": { "code": "permission_denied", "message": "The credentials do not permit this action.", "request_id": "req_…" } } ``` ### 429 ```json { "error": { "code": "quota_limit_reached", "message": "A usage or inventory limit of the Company was reached.", "request_id": "req_…" } } ``` ### 503 ```json { "error": { "code": "quota_gate_unavailable", "message": "The limit check itself failed, so the action was not carried out.", "request_id": "req_…" } } ```