# Create a report share link — API reference > Creates a share link for a report run with an optional label, expiry time or never-expire setting. Source: https://upfour.io/docs/api/reports/create-a-report-share-link [Developers](https://upfour.io/docs/api.md)/[Reports](https://upfour.io/docs/api/reports.md) Creates a share link for a report run with an optional label, expiry time or never-expire setting. POST https://app.upfour.io/v1/reports/{runID}/share scope report.write stable [Idempotency-Key supported](https://upfour.io/docs/api/idempotency.md) returns 201 ## Parameters | Field | Type | Description | | --- | --- | --- | | `runID` required | uuid | path parameter | ## Body `application/json` optional 3 fields All other fields3 fields expires_atstring (date-time) · nullable When the link stops working. Without it and without never_expires the link works for 90 days. labelstring A note for yourself; shown in the list of links. never_expiresboolean A link without an end. Cannot be combined with expires_at. ## Returns A successful request returns `201` with application/json. Response fields 1 top-level fields | Field | Type | Description | | --- | --- | --- | | `data` | ReportShareLinkCreated | | | ReportShareLinkCreated · 17 fields FieldTypeDescription `link` ReportShareLink ReportShareLink · 14 fields FieldTypeDescription `created_at` string (date-time) `id` uuid `label` string `organization_id` uuid `report_run_id` uuid `view_count` integer `client_id` uuid `created_by` uuid `expires_at` string (date-time) Absent for a link that never expires. `format` string one of`csv` `json` `pdf` `xlsx` `range_from` string (date-time) `range_to` string (date-time) `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` `revoked_at` string (date-time) `token` string The secret part of the link; shown only in this answer. `url` string The public link of the snapshot, on the Company's report domain when one is set. | | | ## 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. | | 409 | [conflict](https://upfour.io/docs/api/errors#code-conflict) | The request conflicts with the current state. | | 404 | [not_found](https://upfour.io/docs/api/errors#code-not_found) | The requested resource does not exist or is outside the caller's scope. | | 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. | | 503 | [service_unavailable](https://upfour.io/docs/api/errors#code-service_unavailable) | The service or a required dependency is temporarily unavailable. | 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 share links](https://upfour.io/docs/api/reports/list-report-share-links.md) [NextDelete a report share link](https://upfour.io/docs/api/reports/delete-a-report-share-link.md) ## Request ### cURL ```bash curl -s -X POST "https://app.upfour.io/v1/reports/00000000-0000-4000-8000-000000000001/share" \ -H "Authorization: Bearer $UP4_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "label": "Review with the customer", "never_expires": false }' ``` ### JavaScript ```javascript const res = await fetch("https://app.upfour.io/v1/reports/00000000-0000-4000-8000-000000000001/share", { method: "POST", headers: { Authorization: `Bearer ${process.env.UP4_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ label: "Review with the customer", never_expires: false, }), }); console.log(res.status, await res.json()); ``` ### Python ```python import os import requests res = requests.post( "https://app.upfour.io/v1/reports/00000000-0000-4000-8000-000000000001/share", headers={"Authorization": f"Bearer {os.environ['UP4_API_KEY']}"}, json={ "label": "Review with the customer", "never_expires": False, }, ) print(res.status_code, res.json()) ``` ### Go ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "label": "Review with the customer", "never_expires": false }`) req, _ := http.NewRequest("POST", "https://app.upfour.io/v1/reports/00000000-0000-4000-8000-000000000001/share", 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": { "link": { "created_at": "2026-10-27T09:00:00Z", "created_by": "00000000-0000-4000-8000-000000000002", "expires_at": "2027-01-25T09:00:00Z", "format": "pdf", "id": "00000000-0000-4000-8000-000000000003", "label": "Review with the customer", "organization_id": "00000000-0000-4000-8000-000000000004", "range_from": "2026-10-20T09:00:00Z", "range_to": "2026-10-27T09:00:00Z", "report_run_id": "00000000-0000-4000-8000-000000000001", "report_type": "summary", "view_count": 0 }, "token": "••••", "url": "http://example.com:3001/share/reports/••••" } } ``` ### 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_…" } } ``` ### 404 ```json { "error": { "code": "not_found", "message": "The requested resource does not exist or is outside the caller's scope.", "request_id": "req_…" } } ``` ### 409 ```json { "error": { "code": "conflict", "message": "The request conflicts with the current state.", "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_…" } } ```