Upstream Tech API

Simple Overview

GET

https://status.upstreamtech.io/api/v1/status

Get the overall status for a page, without all the complexities of components and notices.

State

operational: No current incidents or underway maintenance.
degraded: One or more current incidents are marked as 'investigating' or 'identified'. Incidents marked as 'recovering' are no longer considered current.
under_maintenance: One or more current maintenance marked as 'underway'

*In the event that both a current incident and an underway maintenance are present, 'degraded' takes priority.

{
    "page": {
        "name": "Upstream Tech",
        "state": "operational",
        "state_text": "All systems are go!",
        "url": "https://status.upstreamtech.io",
        "links": {
            "components": {
                "href": "/v1/components",
                "count": 50
            },
            "notices": {
                "href": "/v1/notices",
                "count": 100
            },
        },
        "created_at": "2023-01-01T00:00:00.000Z",
        "updated_at": "2023-01-01T00:00:00.000Z"
    }
}

List Components

GET

https://status.upstreamtech.io/api/v1/components

Retrieve a paginated list of components and their status, useful to those who want a more detailed explanation of what’s impacted, or just the status of a subset of components.

Also includes a summary of the past 30 days uptime for components that have Metrics enabled.

State: Can be any of “operational”, “degraded” or “under_maintenance”

Filtering Components

If you want to search for certain components, such as those at the top of the tree, or the children of a given parent you can pass the filter parameter.

Example: Only top level components

GET /api/v1/components?filter[parent_id_null]=true

Example: Children of X

GET /api/v1/components?filter[parent_id_eq]=x

{
    "components": [
        {
            "id": 1,
            "state": "operational",
            "name": "Example Component",
            "description": "This is an example component.",
            "parent_id": null,
            "metrics_summary": {
                "timeframe_start": "2023-03-01",
                "timeframe_end": "2023-03-31",
                "percentage_uptime": {
                    "percent": 97.260273972602,
                    "words": "97.26%"
                },
                "url": "https://status.upstreamtech.io/components/east-coast/metrics"
            },
            "links": {
                "children": {
                    "href": "/api/v1/components?filter[parent_id_eq]=1",
                    "count": 1,
                }
            },
            "created_at": "2023-01-01T00:00:00.000Z",
            "updated_at": "2023-01-01T00:00:00.000Z"
        },
        {
            "id": 2,
            "state": "operational",            
            "name": "Sub-Component",
            "description": "This is an example sub-component.",
            "parent_id": 1,
            "metrics_summary": null,
            "links": {
                "children": {
                    "href": "/api/v1/components?filter[parent_id_eq]=2",
                    "count": 0,
                }
            },
            "created_at": "2023-01-01T00:00:00.000Z",
            "updated_at": "2023-01-01T00:00:00.000Z"
        }
    ],
    "meta": {
        "count": 25,
        "total_count": 50,
        "next_page": "/api/v1/components?page=2"
    }
}

Component Metrics

GET

https://status.upstreamtech.io/api/v1/components/:id/metrics

Get the Percentage Uptime, Mean Time To Recovery and Mean Time Between Failures within a given timeframe for components with Metrics enabled. (the past 30 days by default)

Learn more about how we calculate component uptime.

Request Builder

Component

Timeframe

Required Path Params

component_id: Integer

The ID of the component for which we will calculate metrics.

Optional Query Params

timeframe_start (Optional): Date (yyyy-mm-dd)

The start date of the timeframe for which we will calculate metrics. This date must be, at most, 12 months ago.

Default: 30 days ago
timeframe_end (Optional): Date (yyyy-mm-dd)

The end date of the timeframe for which we will calculate metrics.

Default: Today
show_calculations (Optional): Boolean

Optionally return the equations, timeframe data and unplanned notices we used to calculate the metrics.

Default: False

{
    "component": {
        "id": "123",
        "name": "Network"
    },
    "timeframe_start": "2023-03-01",
    "timeframe_end": "2023-03-31",
    "percentage_uptime": {
        "percent": 97.260273972602,
        "words": "97.26%", 
        "calculation": "100 - ((total_impact_time / total_time) * 100)"
    },
    "mean_time_to_recovery": {
        "seconds": 72000,
        "words": "2 Hours",
        "calculation": "total_impact_time / notices.count"
    },
    "mean_time_between_failures": {
        "seconds": 252000,
        "words": "2 Days, 6 Hours",
        "calculation": "(total_time - total_impact_time) / notices.count"
    },
    "url": "https://status.upstreamtech.io/components/east-coast/metrics?past_x_days=custom&timeframe_end=2031-03-01&timeframe_start=2023-03-01",
    "calculation_data_in_timeframe": {
        "total_time": {
            "seconds": 2592000,
            "words": "30 Days"
        },
        "total_impact_time": {
            "seconds": 72000,
            "words": "20 Hours"
        },
        "notices": {
            "href": "/api/v1/notices?filter[components_id]=123&filter[impact_timeframe_overlaps][]=2023-03-01T00:00:00&filter[impact_timeframe_overlaps][]=2023-03-31T59:59:59",
            "count": 10
        }
    }
}

List Notices

GET

https://status.upstreamtech.io/api/v1/notices

Retrieve a paginated list of notices for a page, past, present and future.

Type: Can be either "planned" or "unplanned"
Timeline State: Can be any of “future”, “present”, “past_recent” or “past_distant”
State: For “unplanned” notices can be any of “investigating”, “identified”, “recovering”, “resolved” or “false_alarm”
For “planned” notices can be any “scheduled”, “underway” or “complete”

This list only contains basic details, for more information such as the impacted components, or the entire progress update history request detailed notice information.

Filtering Notices

If you want to search for certain notices, such as planned maintenances, or only current incidents you can do so by passing the “filter” query string parameter.

Example: Only retrieve planned maintenance.

GET /api/v1/notices?filter[type_eq]=planned

Example: Only retrieve current unplanned notices.

GET /api/v1/notices?filter[timeline_state_eq]=present&filter[type_eq]=unplanned

You can mix and match other "type" and "timeline_state" values in the filter, so you have the flexibility to return just the records you need.

{
    "notices": [
        {
            "id": 1,
            "type": "unplanned",
            "timeline_state": "present",
            "state": "investigating",
            "subject": "Current Incident",
            "url": "https://status.upstreamtech.io/notices/xxx-current-incident",
            "began_at": "2023-01-01T00:00:00.000Z",
            "ended_at": null,
            "created_at": "2023-01-01T00:00:00.000Z",
            "updated_at": "2023-01-01T00:00:00.000Z",
            "impact_time": {
                "seconds": 120,
                "words": "2 minutes"
            },
            "links": {
                "self": "/api/notices/1"
            },
            "latest_update": {
                "state": "investigating",
                "content": "We are currently investigating an issue with our service."
                "created_at": "2023-01-01T00:00:00.000Z",
                "updated_at": "2023-01-01T00:00:00.000Z"
            }
        },
        {
            "id": 2,
            "type": "planned",
            "timeline_state": "future",
            "state": "scheduled",
            "subject": "Planned Maintenance",
            "url": "https://status.upstreamtech.io/notices/xxx-planned-maintenance",
            "begins_at": "2023-01-01T00:00:00.000Z",
            "ends_at": "2023-01-01T01:00:00.000Z",
            "began_at": null,
            "ended_at": null,
            "created_at": "2023-01-01T00:00:00.000Z",
            "updated_at": "2023-01-01T00:00:00.000Z",
            "links": {
                "self": "/api/notices/2"
            },
            "latest_update": {
                "state": "scheduled",
                "content": "We have some upcomming maintenance planned."
                "created_at": "2023-01-01T00:00:00.000Z",
                "updated_at": "2023-01-01T00:00:00.000Z"
            }
        }
    ],
    "meta": {
        "count": 25,
        "total_count": 100,
        "next_page": "/api/v1/notices?page=2"
    }
}

Detailed Notice Information

GET

https://status.upstreamtech.io/api/v1/notices/:id

Retrieve the detail for a given notice, including its impacted components and its full list of progress updates.

{
    "notice": {
        "id": 1,
        "type": "unplanned",
        "timeline_state": "present",
        "state": "investigating",
        "subject": "Current Incident",
        "url": "https://status.upstreamtech.io/notices/xxx-current-incident",        
        "began_at": "2023-01-01T00:00:00.000Z",
        "ended_at": null,
        "created_at": "2023-01-01T00:00:00.000Z",
        "updated_at": "2023-01-01T00:00:00.000Z",
        "impact_time": {
            "seconds": 120,
            "words": "2 minutes"
        },
        "links": {
            "self": "/api/notices/1"
        },
        "components": [
            {
                "id": 1,
                "state": "operational",
                "name": "Example Component",
                "description": "This is an example component.",
                "parent_id": null,
                "created_at": "2023-01-01T00:00:00.000Z",
                "updated_at": "2023-01-01T00:00:00.000Z"
            }
        ],
        "updates": [
            {
                "state": "investigating",
                "content": "We are currently investigating an issue with our service."
                "created_at": "2023-01-01T00:00:00.000Z",
                "updated_at": "2023-01-01T00:00:00.000Z"
            }
        ]
    }
}

Pagination

Collections such as “components” and “notices” only return a maximum of 25 records per request. Larger collections are split into multiple pages and contain a URL to retrieve the next page in the collection.

We also include a count of the records on this page and the total record count across all pages.

{
    "notices": [],
    "meta": {
        "count": 25,
        "total_count": 100,
        "next_page": "/v1/notices?page=2"
    }
}

Fair Use

The Status API allows developers to build on and benefit from the Sorry™ platform. At the same time, we must protect our system and our users’ rights, rate limiting to 10 requests per second.