Postman Collection Runs API
The Collection Runs API enables you to programmatically run collections, schedule runs, and retrieve results for continuous integration and delivery pipelines.
OpenAPI Specification
openapi: 3.1.0
info:
title: Postman Collection Runs API
description: |
The Postman Collection Runs API enables you to programmatically run
collections and retrieve run results. This is useful for continuous
integration and delivery pipelines, enabling you to execute API tests
and retrieve results programmatically.
## Authentication
All requests require an API key passed in the `x-api-key` header.
## Rate Limits
Collection run limits vary by plan. Free plans include 25 collection
runs per month.
version: '1.0.0'
contact:
name: Postman Developer Support
url: https://learning.postman.com/docs/developer/postman-api/intro-api/
email: [email protected]
license:
name: Postman Terms of Service
url: https://www.postman.com/legal/terms/
servers:
- url: https://api.getpostman.com
description: Postman Production API Server
tags:
- name: Collection Runs
description: Operations for running collections and retrieving results.
security:
- apiKeyAuth: []
paths:
/collections/{collectionId}/runs:
get:
tags:
- Collection Runs
summary: Postman Get collection runs
operationId: getCollectionRuns
description: >-
Gets the run history for a collection. Returns a list of past runs
with their status, timing, and summary statistics.
parameters:
- $ref: '#/components/parameters/CollectionIdParam'
- name: cursor
in: query
description: Pagination cursor for the next page of results.
schema:
type: string
- name: limit
in: query
description: Maximum number of results to return.
schema:
type: integer
default: 10
maximum: 100
- name: status
in: query
description: Filter by run status.
schema:
type: string
enum: [queued, running, finished, failed]
- name: source
in: query
description: Filter by run source.
schema:
type: string
enum: [collection_runner, monitor, webhook, schedule, api, newman]
responses:
'200':
description: Successful response with collection runs
content:
application/json:
schema:
type: object
properties:
runs:
type: array
items:
$ref: '#/components/schemas/CollectionRunSummary'
meta:
type: object
properties:
total:
type: integer
nextCursor:
type: string
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'429':
$ref: '#/components/responses/RateLimitError'
/collections/{collectionId}/runs/{runId}:
get:
tags:
- Collection Runs
summary: Postman Get a collection run
operationId: getCollectionRun
description: >-
Gets detailed information about a specific collection run, including
individual request results, test assertions, and response data.
parameters:
- $ref: '#/components/parameters/CollectionIdParam'
- name: runId
in: path
required: true
description: The run's unique ID.
schema:
type: string
responses:
'200':
description: Successful response with run details
content:
application/json:
schema:
type: object
properties:
run:
$ref: '#/components/schemas/CollectionRun'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
'429':
$ref: '#/components/responses/RateLimitError'
components:
securitySchemes:
apiKeyAuth:
type: apiKey
name: x-api-key
in: header
description: Postman API key for authentication.
parameters:
CollectionIdParam:
name: collectionId
in: path
required: true
description: The collection's unique ID or UID.
schema:
type: string
schemas:
CollectionRunSummary:
type: object
description: Summary information about a collection run.
properties:
id:
type: string
description: The run's unique ID
status:
type: string
enum: [queued, running, finished, failed]
description: The run status
source:
type: string
enum: [collection_runner, monitor, webhook, schedule, api, newman]
description: How the run was triggered
startedAt:
type: string
format: date-time
finishedAt:
type: string
format: date-time
stats:
type: object
properties:
requests:
type: object
properties:
total:
type: integer
failed:
type: integer
assertions:
type: object
properties:
total:
type: integer
failed:
type: integer
collectionId:
type: string
environmentId:
type: string
createdBy:
type: string
CollectionRun:
type: object
description: Detailed collection run including individual request results.
properties:
id:
type: string
status:
type: string
enum: [queued, running, finished, failed]
source:
type: string
startedAt:
type: string
format: date-time
finishedAt:
type: string
format: date-time
duration:
type: integer
description: Total run duration in milliseconds
stats:
type: object
properties:
requests:
type: object
properties:
total:
type: integer
failed:
type: integer
assertions:
type: object
properties:
total:
type: integer
failed:
type: integer
executions:
type: array
description: Individual request execution results
items:
type: object
properties:
id:
type: string
itemName:
type: string
request:
type: object
properties:
method:
type: string
url:
type: string
response:
type: object
properties:
statusCode:
type: integer
responseTime:
type: integer
description: Response time in milliseconds
responseSize:
type: integer
description: Response size in bytes
assertions:
type: array
items:
type: object
properties:
name:
type: string
passed:
type: boolean
error:
type: string
collectionId:
type: string
environmentId:
type: string
createdBy:
type: string
responses:
UnauthorizedError:
description: Authentication credentials are missing or invalid
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
name:
type: string
message:
type: string
NotFoundError:
description: The requested resource was not found
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
name:
type: string
message:
type: string
RateLimitError:
description: Too many requests - rate limit exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string