Reports API Reference

This guide provides detailed information about the Reports API endpoints.

Authentication

All report endpoints require authentication using a Project API Token. Include your token in the Authorization header:

bash

Authorization: Bearer YOUR_PROJECT_API_TOKEN

For more information about authentication, see the Authentication Guide.

List Reports

Retrieve a list of all reports for your project.

http

GET /api/v1/reports
Authorization: Bearer YOUR_PROJECT_API_TOKEN

Example with curl:

bash

curl -X GET "https://app.uptinio.com/api/v1/reports?page=1&per_page=25&status=complete" \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json"

Query Parameters

Parameter	Type	Description	Default
page	integer	Page number	1
per_page	integer	Items per page (max: 100)	25
status	string	Filter by status (pending, complete)	all

Note: Reports are ordered by creation date in descending order (most recent first).

Response

json

{
  "data": [
    {
      "uuid": "RPT123",
      "name": "Monthly Uptime Report - January 2024",
      "status": "complete",
      "start_date": "2024-01-01T00:00:00Z",
      "end_date": "2024-01-31T23:59:59Z",
      "resource_uuids": ["NM123", "NM456", "SRV789"],
      "incident_uuids": ["INC123", "INC456"],
      "overall_uptime": 99.95,
      "overall_downtime": 0.05,
      "downtime_events": 2,
      "average_response_time": 125.5,
      "peak_response_time": 350.2,
      "performance_data": {
        "NM123": {
          "success_rate": 99.98,
          "response_time_avg": 120.5
        },
        "NM456": {
          "success_rate": 99.92,
          "response_time_avg": 130.5
        }
      },
      "created_at": "2024-02-01T00:00:00Z",
      "updated_at": "2024-02-01T01:30:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total_pages": 2,
    "total_count": 45
  }
}

Response Fields

Field	Type	Description
data	array	Array of report objects
data[].uuid	string	Report UUID
data[].name	string	Report name
data[].status	string	Report status (pending, complete)
data[].start_date	string	ISO 8601 timestamp of the report start date
data[].end_date	string	ISO 8601 timestamp of the report end date
data[].resource_uuids	array	Array of UUIDs of monitored resources (NetworkMonitors and Servers)
data[].incident_uuids	array	Array of UUIDs of incidents that occurred during the report period
data[].overall_uptime	float\|null	Overall uptime percentage across all resources
data[].overall_downtime	float\|null	Overall downtime percentage across all resources
data[].downtime_events	integer\|null	Total number of downtime events
data[].average_response_time	float\|null	Average response time in milliseconds
data[].peak_response_time	float\|null	Peak response time in milliseconds
data[].performance_data	object	Performance data per resource (keyed by resource UUID)
data[].created_at	string	ISO 8601 timestamp of creation
data[].updated_at	string	ISO 8601 timestamp of last update
meta	object	Pagination metadata
meta.current_page	integer	Current page number
meta.per_page	integer	Number of items per page
meta.total_pages	integer	Total number of pages
meta.total_count	integer	Total number of items

Get Report

Retrieve details of a specific report.

http

GET /api/v1/reports/:uuid
Authorization: Bearer YOUR_PROJECT_API_TOKEN

Example with curl:

bash

curl -X GET https://app.uptinio.com/api/v1/reports/RPT123 \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{
  "uuid": "RPT123",
  "name": "Monthly Uptime Report - January 2024",
  "status": "complete",
  "start_date": "2024-01-01T00:00:00Z",
  "end_date": "2024-01-31T23:59:59Z",
  "resource_uuids": ["NM123", "NM456", "SRV789"],
  "incident_uuids": ["INC123", "INC456"],
  "overall_uptime": 99.95,
  "overall_downtime": 0.05,
  "downtime_events": 2,
  "average_response_time": 125.5,
  "peak_response_time": 350.2,
  "performance_data": {
    "NM123": {
      "success_rate": 99.98,
      "response_time_avg": 120.5
    },
    "NM456": {
      "success_rate": 99.92,
      "response_time_avg": 130.5
    }
  },
  "created_at": "2024-02-01T00:00:00Z",
  "updated_at": "2024-02-01T01:30:00Z"
}

Create Report

Create a new report. The report will be generated in the background and its status will be pending until generation is complete.

http

POST /api/v1/reports
Authorization: Bearer YOUR_PROJECT_API_TOKEN
Content-Type: application/json

Example with curl:

bash

curl -X POST https://app.uptinio.com/api/v1/reports \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "report": {
      "name": "Q1 2024 Report",
      "start_date": "2024-01-01T00:00:00Z",
      "end_date": "2024-03-31T23:59:59Z",
      "resource_uuids": ["NM123", "NM456", "SRV789"]
    }
  }'

Request Body

Parameter	Type	Description	Required
report	object	Report object	Yes
report.name	string	Report name	Yes
report.start_date	string	ISO 8601 timestamp of the report start date	Yes
report.end_date	string	ISO 8601 timestamp of the report end date	Yes
report.resource_uuids	array	Array of UUIDs of resources to include in the report (NetworkMonitors and Servers)	Yes

Note:

start_date must be before end_date
resource_uuids must contain at least one UUID
Dates should be in ISO 8601 format (e.g., 2024-01-01T00:00:00Z or 2024-01-01T00:00:00+00:00)

Response

json

{
  "uuid": "RPT456",
  "name": "Q1 2024 Report",
  "status": "pending",
  "start_date": "2024-01-01T00:00:00Z",
  "end_date": "2024-03-31T23:59:59Z",
  "resource_uuids": ["NM123", "NM456", "SRV789"],
  "incident_uuids": [],
  "overall_uptime": null,
  "overall_downtime": null,
  "downtime_events": null,
  "average_response_time": null,
  "peak_response_time": null,
  "performance_data": {},
  "created_at": "2024-04-01T00:00:00Z",
  "updated_at": "2024-04-01T00:00:00Z"
}

Status Code: 201 Created

Error Response

If the request is invalid, you'll receive a 422 Unprocessable Entity response:

json

{
  "error": "Failed to create report",
  "errors": [
    "Name can't be blank",
    "Start date must be before end date"
  ]
}

Update Report

Update an existing report. Only pending reports should be updated, as complete reports contain generated data.

http

PATCH /api/v1/reports/:uuid
Authorization: Bearer YOUR_PROJECT_API_TOKEN
Content-Type: application/json

Example with curl:

bash

curl -X PATCH https://app.uptinio.com/api/v1/reports/RPT123 \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "report": {
      "name": "Updated Report Name",
      "resource_uuids": ["NM123", "NM456"]
    }
  }'

Request Body

Parameter	Type	Description	Required
report	object	Report object	Yes
report.name	string	Report name	No
report.start_date	string	ISO 8601 timestamp of the report start date	No
report.end_date	string	ISO 8601 timestamp of the report end date	No
report.resource_uuids	array	Array of UUIDs of resources to include in the report	No

Note: All fields are optional. Only include the fields you want to update.

Response

json

{
  "uuid": "RPT123",
  "name": "Updated Report Name",
  "status": "pending",
  "start_date": "2024-01-01T00:00:00Z",
  "end_date": "2024-01-31T23:59:59Z",
  "resource_uuids": ["NM123", "NM456"],
  "incident_uuids": [],
  "overall_uptime": null,
  "overall_downtime": null,
  "downtime_events": null,
  "average_response_time": null,
  "peak_response_time": null,
  "performance_data": {},
  "created_at": "2024-02-01T00:00:00Z",
  "updated_at": "2024-02-01T02:00:00Z"
}

Error Response

If the request is invalid, you'll receive a 422 Unprocessable Entity response:

json

{
  "error": "Failed to update report",
  "errors": [
    "Start date must be before end date"
  ]
}

Delete Report

Delete a report.

http

DELETE /api/v1/reports/:uuid
Authorization: Bearer YOUR_PROJECT_API_TOKEN

Example with curl:

bash

curl -X DELETE https://app.uptinio.com/api/v1/reports/RPT123 \
  -H "Authorization: Bearer YOUR_PROJECT_API_TOKEN" \
  -H "Content-Type: application/json"

Response

json

{
  "message": "Report deleted successfully"
}

Status Code: 200 OK

Report Status

Reports have two possible statuses:

pending: The report is being generated. Metrics and performance data are not yet available.
complete: The report has been generated and all metrics are available.

When a report is created, it starts with status pending. A background job processes the report and updates it to complete when finished. Once complete, the report includes:

Overall uptime and downtime percentages
Average and peak response times
Downtime events count
Performance data per resource
Incident UUIDs that occurred during the report period

Error Codes

Code	Description
report_not_found	The specified report does not exist
invalid_request	The request parameters are invalid
unauthorized	Invalid or missing authentication token

Reports API Reference ​

Authentication ​

List Reports ​

Query Parameters ​

Response ​

Response Fields ​

Get Report ​

Response ​

Create Report ​

Request Body ​

Response ​

Error Response ​

Update Report ​

Request Body ​

Response ​

Error Response ​

Delete Report ​

Response ​

Report Status ​

Error Codes ​

Next Steps ​

Reports API Reference

Authentication

List Reports

Query Parameters

Response

Response Fields

Get Report

Response

Create Report

Request Body

Response

Error Response

Update Report

Request Body

Response

Error Response

Delete Report

Response

Report Status

Error Codes

Next Steps