Postman Collection Runs API
The Collection Runs API programmatically launches collection runs, retrieves run results, and powers integration with Newman, the Postman CLI, and CI/CD pipelines for automated test execution.
OpenAPI Specification
openapi: 3.1.0
info:
title: Postman APIs API Comments Collection Runs API
description: 'The Postman APIs API enables you to manage your API definitions in Postman''s
API Builder. You can create APIs, manage versions, add schemas (OpenAPI,
GraphQL, etc.), and link collections, environments, mock servers, monitors,
and documentation to your API definitions.
## Authentication
All requests require an API key passed in the `x-api-key` header.
## Rate Limits
Standard Postman API rate limits apply.
'
version: 1.0.0
contact:
name: Postman Developer Support
url: https://learning.postman.com/docs/developer/postman-api/intro-api/
email: help@postman.com
license:
name: Postman Terms of Service
url: https://www.postman.com/legal/terms/
servers:
- url: https://api.getpostman.com
description: Postman Production API Server
security:
- apiKeyAuth: []
tags:
- name: Collection Runs
description: Operations for running collections and retrieving results.
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:
responses:
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
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
RateLimitError:
description: Too many requests - rate limit exceeded
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
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
securitySchemes:
apiKeyAuth:
type: apiKey
name: x-api-key
in: header
description: Postman API key for authentication.