Postman Monitors API
The Monitors API runs Postman Collections on a recurring schedule to validate API health, performance, and contract conformance. Surfaces metrics, test results, and notification webhooks for incident response.
OpenAPI Specification
openapi: 3.1.0
info:
title: Postman Monitors API
version: 1.0.0
description: 'Operations tagged monitors across 2 of this provider''s published API definitions: postman-api-openapi.yml, postman-monitors-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
tags:
- name: monitors
paths:
/monitors:
get:
operationId: getMonitors
summary: Get all monitors
description: Gets all monitors.
tags:
- monitors
parameters:
- name: workspace
in: query
description: Return only results found in the given workspace ID.
required: false
schema:
$ref: '#/components/schemas/workspaceId'
- name: active
in: query
description: If true, return only active monitors.
required: false
schema:
$ref: '#/components/schemas/active'
default: false
- name: owner
in: query
description: Return only results that belong to the given user ID.
required: false
schema:
$ref: '#/components/schemas/owner'
- name: collectionUid
in: query
description: Filter the results by a collection's unique ID.
required: false
schema:
$ref: '#/components/schemas/collectionUidQuery'
- name: environmentUid
in: query
description: Filter the results by an environment's unique ID.
required: false
schema:
$ref: '#/components/schemas/environmentUid'
- name: cursor
in: query
description: The pointer to the first record of the set of paginated results. To view the next response, use the `nextCursor` value for this parameter.
required: false
schema:
$ref: '#/components/schemas/cursor'
- name: limit
in: query
description: The maximum number of rows to return in the response, up to a maximum value of 25. Any value greater than 25 returns a 400 Bad Request response.
required: false
schema:
$ref: '#/components/schemas/limitDefault25'
default: 25
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/getMonitors'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/GetMonitorsRequestBadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/GetMonitorsRequestUnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/GetMonitorsRequestForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorNameMessage'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetMonitorsRequestInternalServerError'
post:
operationId: createMonitor
summary: Create a monitor
description: 'Creates a monitor.
**Note:**
- You cannot create monitors for collections added to an API definition.
- If you do not pass the `workspace` query parameter, the system creates the monitor in the oldest personal Internal workspace you own.
'
tags:
- monitors
parameters:
- name: workspace
in: query
description: The workspace's ID.
required: true
schema:
$ref: '#/components/schemas/workspaceId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/createUpdateMonitorResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMonitorRequestBadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMonitorRequestUnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMonitorRequestForbiddenError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMonitorRequestInternalServerError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/createMonitor'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/monitors/{monitorId}:
get:
operationId: getMonitor
summary: Get a monitor
description: Gets information about a monitor.
tags:
- monitors
parameters:
- name: monitorId
in: path
description: The monitor's ID.
required: true
schema:
$ref: '#/components/schemas/monitorId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/getMonitor'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/GetMonitorRequestUnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/GetMonitorRequestForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorNameMessage'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetMonitorRequestInternalServerError'
put:
operationId: updateMonitor
summary: Update a monitor
description: Updates a monitor's [configurations](https://learning.postman.com/docs/monitoring-your-api/setting-up-monitor/#configure-a-monitor).
tags:
- monitors
parameters:
- name: monitorId
in: path
description: The monitor's ID.
required: true
schema:
$ref: '#/components/schemas/monitorId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/createUpdateMonitorResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateMonitorRequestBadRequestError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateMonitorRequestUnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateMonitorRequestForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorNameMessage'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateMonitorRequestInternalServerError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/updateMonitor'
delete:
operationId: deleteMonitor
summary: Delete a monitor
description: Deletes a monitor.
tags:
- monitors
parameters:
- name: monitorId
in: path
description: The monitor's ID.
required: true
schema:
$ref: '#/components/schemas/monitorId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/deleteMonitor'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteMonitorRequestUnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteMonitorRequestForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorNameMessage'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteMonitorRequestInternalServerError'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/monitors/{monitorId}/run:
post:
operationId: runMonitor
summary: Run a monitor
description: 'Runs a monitor and returns its run results.
**Note:**
- If you pass the `async=true` query parameter, the response does not return the `stats`, `executions`, and `failures` responses. To get this information for an asynchronous run, call the GET `/monitors/{id}` endpoint.
- If the call exceeds 300 seconds, the endpoint returns an HTTP `202 Accepted` response. Use the GET `/monitors/{id}` endpoint to check the run''s status in the response''s `lastRun` property. To avoid this, it is recommended that you include the `async=true` query parameter when using this endpoint.
'
tags:
- monitors
parameters:
- name: monitorId
in: path
description: The monitor's ID.
required: true
schema:
$ref: '#/components/schemas/monitorId'
- name: async
in: query
description: If true, runs the monitor asynchronously from the created monitor run task. By default, the server will not respond until the task finishes (`false`).
required: false
schema:
$ref: '#/components/schemas/async'
default: false
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/runMonitor'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/RunMonitorRequestUnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/RunMonitorRequestForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/commonErrorNameMessage'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/RunMonitorRequestInternalServerError'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/runners/{runnerId}/instances:
get:
operationId: getRunnerInstances
summary: Get all runner instances
description: 'Gets all instances of the runner polling Postman for upcoming monitor runs. Instances are runner executions that share the same runner ID and key.
**Note:**
You can get a runner''s ID in the Postman UI if you have an Admin or Super Admin role. To do this, click **Team > Team Settings** in Postman, then click **Runners**. Click the runner you want to get the ID of, then copy its ID from the URL.
'
tags:
- monitors
parameters:
- name: runnerId
in: path
description: The runner's ID.
required: true
schema:
$ref: '#/components/schemas/runnerId'
- name: limit
in: query
description: The maximum number of rows to return in the response, up to a maximum value of 25. Any value greater than 25 returns a 400 Bad Request response.
required: false
schema:
$ref: '#/components/schemas/limitDefault25'
default: 25
- name: cursor
in: query
description: The pointer to the first record of the set of paginated results. To view the next response, use the `nextCursor` value for this parameter.
required: false
schema:
$ref: '#/components/schemas/cursor'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/getRunnerInstances'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/runnerErrorTypeTitleDetailCreatedAt'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/GetRunnerInstancesRequestUnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/GetRunnerInstancesRequestForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/runnerErrorTypeTitleDetailCreatedAt'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetRunnerInstancesRequestInternalServerError'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
/runners/{runnerId}/metrics:
get:
operationId: getRunnerMetrics
summary: Get runner metrics
description: 'Gets the Postman server-side metrics for a runner instance. Metrics include information such as monitor run queues and last polling date.
**Note:**
You can get a runner''s ID in the Postman UI if you have a Team Admin or Super Admin role. To do this, click **Team > Team Settings** in Postman, then click **Runners**. Click the runner you want to get the ID of, then copy its ID from the URL.
'
tags:
- monitors
parameters:
- name: runnerId
in: path
description: The runner's ID.
required: true
schema:
$ref: '#/components/schemas/runnerId'
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/getRunnerMetrics'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/GetRunnerMetricsRequestUnauthorizedError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/GetRunnerMetricsRequestForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/runnerErrorTypeTitleDetailCreatedAt'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/GetRunnerMetricsRequestInternalServerError'
servers:
- url: https://api.postman.com
description: https://api.postman.com
- url: https://api.eu.postman.com
description: https://api.eu.postman.com
components:
schemas:
DeleteMonitorRequestForbiddenError:
oneOf:
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
- $ref: '#/components/schemas/commonErrorNameMessage'
title: DeleteMonitorRequestForbiddenError
MonitorDistributionItems:
type: object
properties:
region:
$ref: '#/components/schemas/MonitorDistributionItemsRegion'
description: The assigned distribution region.
title: MonitorDistributionItems
GetMonitorsMonitorsItems:
type: object
properties:
id:
type: string
description: The monitor's ID.
name:
type: string
description: The monitor's name.
active:
type: boolean
description: Whether the monitor is active (`true`) or inactive (`false`).
uid:
type: string
format: uid
description: The monitor's unique ID.
owner:
type: integer
description: The ID of the user that created the monitor.
collectionUid:
type: string
description: The unique ID of the monitor's associated collection.
environmentUid:
type: string
description: The unique ID of the monitor's associated environment.
description: Information about the monitor.
title: GetMonitorsMonitorsItems
monitorLastRun:
type: object
properties:
status:
type: string
description: The monitor's status after its last run.
startedAt:
type: string
format: date-time
description: The date and time at which the monitor's previous run started.
finishedAt:
type: string
format: date-time
description: The date and time at which the monitor's previous run completed.
stats:
$ref: '#/components/schemas/monitorRunStats'
description: Information about the monitor's previous run.
title: monitorLastRun
commonErrorNameMessageDetails:
type: object
properties:
error:
$ref: '#/components/schemas/CommonErrorNameMessageDetailsError'
title: commonErrorNameMessageDetails
CommonErrorTypeTitleDetailStatusType:
oneOf:
- type: string
format: uri-reference
- type: string
title: CommonErrorTypeTitleDetailStatusType
GetRunnerMetricsRequestForbiddenError:
oneOf:
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
- $ref: '#/components/schemas/commonErrorNameMessage'
title: GetRunnerMetricsRequestForbiddenError
commonErrorTypeTitleDetail:
type: object
properties:
type:
type: string
description: The type of error.
title:
type: string
description: A short summary of the problem.
detail:
$ref: '#/components/schemas/CommonErrorTypeTitleDetailDetail'
description: Information about the error.
title: commonErrorTypeTitleDetail
MonitorRunExecutionsItems:
type: object
properties:
id:
type: number
format: double
description: The execution ID.
item:
$ref: '#/components/schemas/MonitorRunExecutionsItemsItem'
description: Information about the executed item.
request:
$ref: '#/components/schemas/monitorRunRequests'
response:
$ref: '#/components/schemas/monitorRunResponses'
errors:
$ref: '#/components/schemas/monitorRunErrors'
title: MonitorRunExecutionsItems
runMonitor:
type: object
properties:
run:
$ref: '#/components/schemas/RunMonitorRun'
description: Information about the monitor run. If you pass the `async=true` query parameter, the response does not return the `stats`, `executions`, and `failures` responses. To get this information for an asynchronous run, call the GET `/monitors/{id}` endpoint.
title: runMonitor
limitDefault25:
type: integer
default: 25
title: limitDefault25
monitorNotifications:
type: object
properties:
onError:
type: array
items:
$ref: '#/components/schemas/MonitorNotificationsOnErrorItems'
onFailure:
type: array
items:
$ref: '#/components/schemas/MonitorNotificationsOnFailureItems'
description: Information about the monitor's notification settings.
title: monitorNotifications
CreateMonitorRequestForbiddenError:
oneOf:
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
- $ref: '#/components/schemas/commonErrorNameMessage'
title: CreateMonitorRequestForbiddenError
createUpdateMonitorResponse:
type: object
properties:
monitor:
$ref: '#/components/schemas/CreateUpdateMonitorResponseMonitor'
description: Information about the monitor.
title: createUpdateMonitorResponse
monitorSchedule:
type: object
properties:
cron:
type: string
description: 'The monitor''s run frequency, based on the given POSIX cron pattern. For example:
- Every 5 minutes — `*/5 * * * *`
- Every 30 minutes — `*/30 * * * *`
- Every hour — `0 */1 * * *`
- Every 6 hours — `0 */6 * * *`
- Every day at 5 pm — `0 17 * * *`
- Every Monday at 12 pm — `0 12 * * MON`
- Every weekday (Mon — Fri) at 6 am — `0 6 * * MON-FRI`
'
timezone:
type: string
description: The monitor's [timezone](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
description: Information about the monitor's schedule.
title: monitorSchedule
GetMonitorMonitorSchedule:
type: object
properties:
cron:
type: string
description: The monitor's POSIX cron frequency value.
nextRun:
type: string
format: date-time
description: The date and time of monitor's next scheduled run.
timezone:
type: string
description: The monitor's timezone.
description: Information about the monitor's schedule.
title: GetMonitorMonitorSchedule
runnerErrorTypeTitleDetailCreatedAt:
type: object
properties:
type:
type: string
format: uri-reference
description: The [URI reference](https://www.rfc-editor.org/rfc/rfc3986) that identifies the type of problem.
title:
type: string
description: A short summary of the problem.
detail:
type: string
description: Information about the error.
createdAt:
type: string
description: The date and time at which the error occurred.
title: runnerErrorTypeTitleDetailCreatedAt
runnerMeta:
type: object
properties:
model:
type: string
description: The `runnerInstance` value.
action:
type: string
description: The `find` value.
url:
type: string
format: uri-reference
description: The reference URL to the resource.
nextCursor:
type: string
description: The pagination cursor that points to the next record in the results set.
description: The response's meta information for paginated results.
title: runnerMeta
CreateUpdateMonitorResponseMonitor:
type: object
properties:
id:
type: string
description: The monitor's ID.
name:
type: string
description: The monitor's name.
active:
type: boolean
default: true
description: If true, the monitor is active and makes calls to the specified URL.
uid:
type: string
format: uid
description: The monitor's unique ID.
description: Information about the monitor.
title: CreateUpdateMonitorResponseMonitor
GetMonitorsRequestBadRequestError:
oneOf:
- $ref: '#/components/schemas/commonErrorNameMessage'
- $ref: '#/components/schemas/commonErrorNameMessageDetails'
title: GetMonitorsRequestBadRequestError
monitorRunRequests:
type: object
properties:
method:
type: string
description: The HTTP request method.
url:
type: string
format: url
description: The request's URL.
body:
type: object
additionalProperties:
description: Any type
description: Information about the request body, such as Content-Length.
headers:
type: object
additionalProperties:
description: Any type
description: Information about the request headers, such as Content-Type, Accept, encoding, and other information.
timestamp:
type: string
description: The date and time of the request.
description: Information about the monitor run's requests.
title: monitorRunRequests
CreateMonitorRequestBadRequestError:
oneOf:
- $ref: '#/components/schemas/commonErrorNameMessage'
- $ref: '#/components/schemas/commonErrorNameMessageDetails'
title: CreateMonitorRequestBadRequestError
CommonErrorNameMessageError:
type: object
properties:
name:
type: string
description: The error name.
message:
type: string
description: The error message.
description: Information about the error.
title: CommonErrorNameMessageError
GetMonitorsRequestUnauthorizedError:
oneOf:
- $ref: '#/components/schemas/commonErrorTypeTitleDetailStatus'
- $ref: '#/components/schemas/commonErrorNameMessage'
title: GetMonitorsRequestUnauthorizedError
GetMonitorMonitor:
type: object
properties:
id:
type: string
description: The monitor's ID.
name:
type: string
description: The monitor's name.
uid:
type: string
format: uid
description: The monitor's unique ID.
owner:
type: integer
description: The ID of monitor's owner.
active:
type: boolean
default: true
description: If true, the monitor is active and makes calls to the specified URL.
notificationLimit:
type: number
format: double
description: Stop email notifications after the given number consecutive failures.
collectionUid:
type: string
format: uid
description: The unique ID of the monitor's associated collection.
environmentUid:
type: string
format: uid
description: The unique ID of the monitor's associated environment.
jobId:
type: string
description: The job ID of the monitor's latest run.
options:
$ref: '#/components/schemas/monitorOptions'
notifications:
$ref: '#/components/schemas/monitorNotifications'
distribution:
$ref: '#/components/schemas/monitorDistribution'
schedule:
$ref: '#/components/schemas/GetMonitorMonitorSchedule'
description: Information about the monitor's schedule.
retry:
$ref: '#/components/schemas/monitorRetry'
lastRun:
$ref: '#/components/schemas/monitorLastRun'
description: Information about the monitor.
title: GetMonitorMonitor
owner:
type: integer
title: owner
RunMonitorRun:
type: object
properties:
info:
$ref: '#/components/schemas/monitorRunInfo'
stats:
$ref: '#/components/schemas/monitorRunStats'
executions:
$ref: '#/components/schemas/monitorRunExecutions'
failures:
type: array
items:
$ref: '#/components/schemas/RunMonitorRunFailuresItems'
description: If the monitor run failed, information about the run's failures.
description: Information about the monitor run. If you pass the `async=true` query parameter, the response does not return the `stats`, `executions`, and `failures` responses. To get this information for an asynchronous run, call the GET `/monitors/{id}` endpoint.
title: RunMonitorRun
monitorOptions:
type: object
properties:
followRedirects:
type: boolean
description: If true, follow redirects enabled.
requestDelay:
type: number
format: double
description: The monitor's request delay value, in milliseconds.
requestTimeout:
type: number
format: double
description: The monitor's request timeout value, in milliseconds.
strictSSL:
type: boolean
description: If true, strict SSL enabled.
description: Information about the monitor's option settings.
title: monitorOptions
monitorRunResponses:
type: object
properties:
body:
type: object
additionalProperties:
description: Any type
description: Information about the request body, such as Content-Length.
code:
type: number
format: double
description: The response's HTTP status code.
headers:
type: object
additionalProperties:
description: Any type
description: Information about the response headers, such as Content-Type, Accept, encoding, and other information.
responseSize:
type: number
format: double
description: The response size, in bytes.
responseTime:
type: number
format: double
description: The response time, in milliseconds.
description: Information about the monitor run's response.
title: monitorRunResponses
getRunnerMetrics:
type: object
properties:
lastPingAt:
type: string
description: The last date and time the runner sent results to the Postman cloud.
oldestQueuedRunAgeSeconds:
type: integer
description: The age of the monitor, in seconds, that has been waiting the l
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/postman/refs/heads/main/openapi/postman-monitors-api-openapi.yml