Introduction

Welcome to the API Monitoring section of the BlazeMeter API reference! This section will cover the APIs used for creating, updating, and running API monitoring tests and environments, as well as getting the test results, handling test schedules, and handling administration on your account.

The Runscope API provides access to data in your API Monitoring account. This document describes how to authenticate to the API and the resources available. If you have any problems using the Runscope API contact us at support@blazemeter.com

This API reference uses the following conventions for your convenience:

• Language bindings are available in cURL. You can view the code examples and JSON responses in the dark area to the right.

• Links to the API explorer are provided in the following format: API Explorer: /explorer. To use the API explorer, you must first log in to a.blazemeter.com to establish authentication. If you need an account, signup for a free account (first and last name, and a valid email address are required).

Basics

Request Format

All requests to the API are sent over HTTPS and use the following base URL:

https://api.runscope.com

Response Format

Responses are returned as JSON data in the following format (see the right for example).

{
     "data": { ... } or [ ... ],
     "meta": { ... },
     "error": { ... } or null
} 

Response Attributes

Attribute	Description
data	Contains the actual response information for the resource you are accessing. It will either be a JSON object or JSON array depending on what the resource returns.
meta	Contains other extra information about the response. This could include paging information for lists, warnings/errors information, links to other resources, etc.
error	Contains information if the there was an error with your request. This includes a longer description, error codes, and links to more information in our docs. If the request was successful, the error attribute's value will be set to null.

Authentication

All requests to the API require a valid OAuth 2 access token. You can generate an access token using the Web Authorization Flow or use the one that is automatically created for your account when creating a new application. Read the full Authentication docs for details.

To make request an authenticated request to the Runscope API send the Authorization header with the access token value:

Authorization: Bearer <access_token>

Content-Type Header

For API resources where JSON object data is sent in the request body, the 'Content-Type' header is required.

When sending data in the request body, send the data type in the 'Content-Type' header:

Content-Type: application/json

Resources

Check out the Resource Guide to learn more about each API resource.

Authentication Process

The Runscope API uses OAuth 2.0 for authentication. OAuth2 is a protocol that lets applications ask for authorization to an API Monitoring account without getting their password. Access tokens can be limited to specific types of data, and can be revoked by the user at any time.

Applications

To use the API, you must first create an Application.

Applications must have a name, website URL, and callback URL. Once you create an application you'll be given a Client ID and a Client Secret to use in the authorization flow.

When you create the application, we automatically authorize your own account for it and generate an access_token for your own use. This makes it easy to start using the API for personal use without building a web flow.

To build applications that access data on other API Monitoring Accounts, you will need to send users through the Web Application Flow.

Web Application Flow

Step 1: Redirect to Authorization Dialog

Authorize URL

curl 'https://www.runscope.com/signin/oauth/authorize'

Response 302 Found

Location: https://www.runscope.com/signin/oauth/authorize?client_id=XXXXXX
                                                         &redirect_uri=https://example.com
                                                         &response_type=code
                                                         &scope=api:read%20messsage:write
                                                         &state=random_value

To begin the OAuth flow, redirect a user to the Authorize URL.

Authorize URL Parameters

Attributes

• client_id string

  required

  The Client ID of your application

• redirect_uri string

  required

  The Callback URL of your application. After authorizing your application a redirect will be made to this URL with an authorization code

• response_type string

  required

  The desired grant type, as per the OAuth 2.0 spec. The only current valid value is response_type=code

• scope string

  A space separated list of scopes. Valid scopes are listed below

• state string

  An unguessable random string. This state will be sent back to your application's Callback URL. It should be used to protect against cross-site request forgery attacks on your application

Available Scopes

Scopes

• api:read string

  required

  Default read access. Allows you to see most of the user's account information including message streams and buckets

• bucket:auth_token string

  Allows you to read authenticated buckets

• bucket:write string

  Allows you to read all bucket information, including Authenticated Buckets

• message:write string

  Allows you to create new buckets on behalf of the user (up to their plan limit)

• account:email string

  Allows you to read the email addresses of user accounts

• team:read string

  Allows you to read team details such as lists of team members and external service integrations

• test:read string

  Allows you to read the details of API tests

• test:write string

  Allows you to update and delete details of API tests

The user will be presented with the following confirmation screen:

After clicking Authorize, they will be redirected to you Callback URL.

Step 2: We Request Your Callback URL

Sample Callback URL Request (Authorization Granted)

curl 'https://example.com/oauth_callback?code=38a6c89f-7c15-4c95-ab48-8b733849958b'

Once the app has been authorized, Runscope will redirect the user back to your Callback URL with an authorizaton code included in a code URL parameter. If the user declines to authorize your app, a redirect to your Callback URL will be issued with a error=access_denied URL parameter.

Authorization Codes are only valid for a short time, you must exhange the code for an access token with 60 seconds or you will have to send the user through the authorization flow again.

Step 3: Exchange Code for Access Token

Access Token URL

curl 'https://www.runscope.com/signin/oauth/access_token \
curl 'https://www.runscope.com/signin/oauth/access_token' \
    -X POST \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'client_id=1aa59acb-b1a2-4cfe-beaa-aa105fbf8bb9&client_secret=51d8caf2-d990-4e28-aa27-9dd2c745a1cf&code=38a6c89f-7c15-4c95-ab48-8b733849958b&grant_type=authorization_code&redirect_uri=https://my.domain.com'

Response 200 OK

{
    "access_token":"43541d4a-c4b0-43b1-bd26-33231e06b71d",
    "token_type":"bearer"
}

You may now use this code to retrieve an Access Token from the Access Token URL.

We will return a response with an access_token. This access token may be stored and used until the user revokes access to your application.

Access Token Parameters

Parameters

• client_id string

  required

  The Client ID of your application

• client_secret string

  required

  The Client Secret of the application

• code string

  required

  The code you received in your Callback URL

• grant_type string

  required

  The only valid value is authorization_code

• redirect_uri string

  The Callback URL specified for this application

API Resources

Root

Root URL

curl 'https://api.runscope.com/'

Response 200 OK

{
    "data": {
        "bucket_list_url": "https://api.runscope.com/buckets",
        "current_account_url": "https://api.runscope.com/account"
    },
    "meta": {
        "status": "success"
    }
}

The root resource returns an object with links to other resources.

Root Response Attributes

Attributes

• bucket_list_url string

  The URL for this account's list of buckets. See Bucket List

• current_account_url string

  The URL for this account's detail resource. See Account

Other Resources

Resources

• Tests

  Create, modify, delete and view API tests and results

  Show/Hide Child Attributes

  • Steps

    Create, reorder and modify test steps

  • Environments

    Create and modify test and shared environments

  • Schedules

    Create and modify the scheduling of tests

  • Results string

    View the results of test runs

• Account string

  Information about the authorized account

• Buckets array

  Details for the buckets available to the authorized account

• Integrations array

  Details for the 3rd-party connected services

• Regions array

  Information about the available Service Regions

• Teams array

  Information about the members of a team

Tests

Create and view the details for tests within a bucket.

Test List

Test List

curl 'https://api.runscope.com/buckets/<bucket_key>/tests'

Response 200 OK

{
    "data": [
        {
            "created_at": 1438828991,
            "created_by": {
                "email": "grace@example.com",
                "name": "Grace Hopper",
                "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"
            },
            "default_environment_id": "1eeb3695-5d0f-467c-9d51-8b773dce29ba",
            "description": "An internal API!",
            "name": "My Service",
            "id": "9b47981a-98fd-4dac-8f32-c05aa60b8caf"
        }
    ],
    "error": null,
    "meta": {
        "status": "success"
    }
}

A list of all the tests for this bucket.

Test List Request Parameters

Parameters

• count integer

  Maximum number of tests to return. Defaults to 10 if not specified

• offset integer

  Number of tests to skip when retrieving tests

Creating Tests

Creating Tests Single Test

curl 'https://api.runscope.com/buckets/<bucket_key>/tests' \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"name": "Sample Name","description": "My test description"}'

The following JSON sample provides a more readable version of the content contained in the above curl example. This example represents the attributes and values contained in the -d flag of the curl example.

Creating Tests Sample POST Body(JSON) for Single Test

{ 
    "name": "Sample Name",
    "description": "My test description"
}

Creating Tests Multiple Tests

curl 'https://api.runscope.com/buckets/<bucket_key>/tests' \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '[{"name": "Sample Name #1","description": "My test description #1"},{"name": "Sample Name #2","description": "My test description #2"}]'

The following JSON sample provides a more readable version of the content contained in the above curl example. This example represents the attributes and values contained in the -d flag of the curl example.

Creating Tests Sample POST Body(JSON) for Multiple Tests

[
    { 
        "name": "Sample Name #1",
        "description": "My test description #1"
    },
    {
        "name": "Sample Name #2",
        "description": "My test description #2"
    }
]

Create one or more tests in this bucket.

Creating Tests Data Attributes

Response 201 CREATED

{
    "data": {
        "created_at": 1438832081,
        "created_by": {
            "email": "grace@example.com",
            "name": "Grace Hopper",
            "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"
        },
        "default_environment_id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
        "description": null,
        "environments": [
            {
                "emails": {
                    "notify_all": false,
                    "notify_on": "all",
                    "notify_threshold": 1,
                    "recipients": []
                },
                "initial_variables": {
                    "base_url": "https://api.example.com"
                },
                "integrations": [
                    {
                        "description": "Pagerduty Account",
                        "integration_type": "pagerduty",
                        "id": "53776d9a-4f34-4f1f-9gff-c155dfb6692e"
                    }
                ],
                "name": "Test Settings",
                "parent_environment_id": null,
                "preserve_cookies": false,
                "regions": [
                    "us1"
                ],
                "remote_agents": [],
                "script": "",
                "test_id": "626a024c-f75e-4f57-82d4-104fe443c0f3",
                "id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
                "verify_ssl": true,
                "webhooks": null
            }
        ],
        "last_run": null,
        "name": "Sample Name",
        "schedules": [],
        "steps": [
            {
                "assertions": [
                    {
                        "comparison": "is_equal",
                        "source": "response_status",
                        "value": 200
                    }
                ],
                "auth": {},
                "body": "",
                "form": {},
                "headers": {},
                "method": "GET",
                "note": "",
                "step_type": "request",
                "url": "https://yourapihere.com/",
                "id": "53f8e1fd-0989-491a-9f15-cc055f27d097",
                "variables": []
            }
        ],
        "trigger_url": "http://api.runscope.com/radar/b96ecee2-cce6-4d80-8f07-33ac22a22ebd/trigger",
        "id": "626a024c-f75e-4f57-82d4-104fe443c0f3"
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}

Attributes

• name string

  The name of this test

• description string

  description

Test Detail

Test Detail

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>' \
    -H 'Authorization: Bearer <access_token>'

Retrieve the details of a given test by ID.

Test Detail Response Attributes

Response 200 OK

{
    "data": {
        "created_at": 1438832081,
        "created_by": {
            "email": "grace@example.com",
            "name": "Grace Hopper",
            "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"
        },
        "default_environment_id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
        "description": null,
        "environments": [
            {
                "emails": {
                    "notify_all": false,
                    "notify_on": "all",
                    "notify_threshold": 1,
                    "recipients": []
                },
                "initial_variables": {
                    "base_url": "https://api.example.com"
                },
                "integrations": [
                    {
                        "description": "Pagerduty Account",
                        "integration_type": "pagerduty",
                        "id": "53776d9a-4f34-4f1f-9gff-c155dfb6692e"
                    }
                ],
                "name": "Test Settings",
                "parent_environment_id": null,
                "preserve_cookies": false,
                "regions": [
                    "us1"
                ],
                "remote_agents": [],
                "script": "",
                "test_id": "626a024c-f75e-4f57-82d4-104fe443c0f3",
                "id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
                "verify_ssl": true,
                "webhooks": null
            }
        ],
        "last_run": null,
        "name": "Sample Name",
        "schedules": [],
        "steps": [
            {
                "assertions": [
                    {
                        "comparison": "is_equal",
                        "source": "response_status",
                        "value": 200
                    }
                ],
                "auth": {},
                "body": "",
                "form": {},
                "headers": {},
                "method": "GET",
                "note": "",
                "step_type": "request",
                "url": "https://yourapihere.com/",
                "id": "53f8e1fd-0989-491a-9f15-cc055f27d097",
                "variables": []
            }
        ],
        "trigger_url": "http://api.runscope.com/radar/b96ecee2-cce6-4d80-8f07-33ac22a22ebd/trigger",
        "id": "626a024c-f75e-4f57-82d4-104fe443c0f3"
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}

Attributes

• created_at integer

  Date the test was created (in Epoch time)

• created_by object

  Details of the user who created this test

  Show/Hide Child Attributes

  • email string

    The email of the user who created this test

  • name string

    Thea name of the user who created this test

  • id string

    The unique identifier for the user who created this test

• default_environment_id string

  The default environment for the test

• description null

  Long-form description of the test

• environments array

  A list of environments for the test

• name string

  The name of the test

• schedules array

  A list of schedules for the test

• steps array

  An ordered list of the steps for the test

• trigger_url string

  The trigger URL for this test

• id string

  The unique identifier for the test

Starting a Test Run

To programmatically initiate a test run, use a Trigger URL.

Modifying Tests

Modifying Tests

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>' \
    -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"name": "Sample Name","description": "My test description"}'

Modify a test's name, description, default environment and its steps. To modify other individual properties of a test, make requests to the steps, environments, and schedules subresources of the test.

Modifying Tests Data Attributes

The following JSON sample provides a more readable version of the content contained in the above curl example. This example represents the attributes and values contained in the -d flag of the curl example. The PUT body for the request must be a JSON-encoded object with following parameters, parameters omitted will not be modified.

Modifying Tests Sample PUT Body(JSON)

{ 
    "name": "Sample Name",
    "description": "My test description"
}

Response 200 OK

{
    "data": {
        "created_at": 1438832081,
        "created_by": {
            "email": "grace@example.com",
            "name": "Grace Hopper",
            "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"
        },
        "default_environment_id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
        "description": null,
        "environments": [
            {
                "emails": {
                    "notify_all": false,
                    "notify_on": "all",
                    "notify_threshold": 1,
                    "recipients": []
                },
                "initial_variables": {
                    "base_url": "https://api.example.com"
                },
                "integrations": [
                    {
                        "description": "Pagerduty Account",
                        "integration_type": "pagerduty",
                        "id": "53776d9a-4f34-4f1f-9gff-c155dfb6692e"
                    }
                ],
                "name": "Test Settings",
                "parent_environment_id": null,
                "preserve_cookies": false,
                "regions": [
                    "us1"
                ],
                "remote_agents": [],
                "script": "",
                "test_id": "626a024c-f75e-4f57-82d4-104fe443c0f3",
                "id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
                "verify_ssl": true,
                "webhooks": null
            }
        ],
        "last_run": null,
        "name": "Sample Name",
        "schedules": [],
        "steps": [
            {
                "assertions": [
                    {
                        "comparison": "is_equal",
                        "source": "response_status",
                        "value": 200
                    }
                ],
                "auth": {},
                "body": "",
                "form": {},
                "headers": {},
                "method": "GET",
                "note": "",
                "step_type": "request",
                "url": "https://yourapihere.com/",
                "id": "53f8e1fd-0989-491a-9f15-cc055f27d097",
                "variables": []
            }
        ],
        "trigger_url": "http://api.runscope.com/radar/b96ecee2-cce6-4d80-8f07-33ac22a22ebd/trigger",
        "id": "626a024c-f75e-4f57-82d4-104fe443c0f3"
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}

Attributes

• name string

  The name of the test

• description string

  Long-form description of the test

• default_environment_id string

  The default environment for the test

• steps array

  An ordered list of the steps for the test

Deleting Tests

Deleting Tests

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>' \
    -X DELETE \
    -H 'Authorization: Bearer <access_token>'

Response 204 NO CONTENT

Delete a test, including all steps, schedules, test-specific environments and results.

List Revisions

List Revisions

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/revisions' \
    -H 'Authorization: Bearer <access_token>'

Response 200 OK

{
    "error": null,
    "meta": {
        "status": "success"
    },
    "data": {
        "test_revisions": [
            {
                "uuid": "afaeb32b-2114-4b01-b67c-c8b7720e3e64",
                "timestamp": 1681825927.81,
                "item_type": "radar_test",
                "author_uuid": "a4b266a5-ec1a-4928-8790-86290ff5c1e4",
                "author_name": "Jane Doe",
                "author_email": "user9090@perforce.com",
                "organization_id": "8c7b00de-a962-4037-aa07-2cc294a32afd",
                "bucket_key": "wyleuxihrgtg",
                "source": "dashboard"
            },

        ],
        "env_revisions": {
            "e4e1cc35-9f0f-404e-9022-cab37c3beae1": [
                {
                    "uuid": "e4e1cc35-9f0f-404e-9022-cab37c3beae1",
                    "timestamp": 1681821157.06,
                    "item_type": "environment",
                    "author_uuid": "a4b266a5-ec1a-4928-8790-86290ff5c1e4",
                    "author_name": "Jane Doe",
                    "author_email": "user9090@perforce.com",
                    "organization_id": "8c7b00de-a962-4037-aa07-2cc294a32afd",
                    "bucket_key": "wyleuxihrgtg",
                    "source": "dashboard"
                }
            ]
        }
    }
}

Returns a list of revisions for a test and its environments.

Steps

Modify the steps for a given test.

Adding Test Steps

Add steps to a test by POSTing a type-specific payload to the Test Steps resource. There are several types of test steps available:

• request - A standard HTTP request step.
• pause - Pause the execution of the test for the given duration.
• condition - Evaluate a condition and optionally other steps within the condition.
• ghost-inspector - Execute a Ghost Inspector UI test and wait for the results.
• subtest - Execute a different Runscope Test and wait for the results.

Request Step

Adding Request Step

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/steps' \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"step_type":"request","method":"POST","url":"https://yourapihere.com/example/path","body":"{ \"hello\": \"world\" }",assertions": [{"source":"response_status","comparison":"equal_number","value": 200}],"variables":[{"name":"source_ip","property":"origin","source":"response_json"}],"auth": {"username":"authBasicUsername","auth_type":"basic","password":"authBasicPassword"},"headers": {"Content-Type": ["application/json"],"Accept": [*/*"]},"scripts": ["log(\"This is a sample post-response script\");","log(\"This is a second sample post-response script\");"],"before_scripts": ["log(\"This is a sample pre-request script\");","log(\"This is a second sample pre-request script\");"],"note":"get example data"}'

The POST body must be a JSON object.

Adding Request Steps Request Attributes

The following JSON sample provides a more readable version of the content contained in the above curl example. This example represents the attributes and values contained in the -d flag of the curl example.

Adding Request Step Sample POST Body(JSON) for Request Step

{ 
    "step_type": "request",
    "method": "POST",
    "url": "https://yourapihere.com/example/path",
    "body": "{ \"hello\": \"world\" }",
    "assertions": [
        {
            "source": "response_status", 
            "comparison": "equal_number", 
            "value": 200
        }
    ],
    "variables": [
        {
            "name": "source_ip",
            "property": "origin",
            "source": "response_json"
        }    
    ],
    "auth": {
        "username": "authBasicUsername",
        "auth_type": "basic",
        "password": "authBasicPassword"
    },
    "headers": {
        "Content-Type": [
            "application/json"
        ],
        "Accept": [
            "*/*"
        ]
    },
    "scripts": [
        "log(\"This is a sample post-response script\");",
        "log(\"This is a second sample post-response script\");"
    ],
    "before_scripts": [
        "log(\"This is a sample pre-request script\");",
        "log(\"This is a second sample pre-request script\");"
    ],
    "skipped": false,
    "note": "get example data"
}

Response 201 CREATED

{
    "data": {
        "created_at": 1438832081,
        "created_by": {
            "email": "grace@example.com",
            "name": "Grace Hopper",
            "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"
        },
        "default_environment_id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
        "description": null,
        "environments": [
            {
                "emails": {
                    "notify_all": false,
                    "notify_on": "all",
                    "notify_threshold": 1,
                    "recipients": []
                },
                "initial_variables": {
                    "base_url": "https://api.example.com"
                },
                "integrations": [
                    {
                        "description": "Pagerduty Account",
                        "integration_type": "pagerduty",
                        "id": "53776d9a-4f34-4f1f-9gff-c155dfb6692e"
                    }
                ],
                "name": "Test Settings",
                "parent_environment_id": null,
                "preserve_cookies": false,
                "regions": [
                    "us1"
                ],
                "remote_agents": [],
                "script": "",
                "test_id": "626a024c-f75e-4f57-82d4-104fe443c0f3",
                "id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
                "verify_ssl": true,
                "webhooks": null
            }
        ],
        "last_run": null,
        "name": "Sample Name",
        "schedules": [],
        "steps": [
            {
                "assertions": [
                    {
                        "comparison": "is_equal",
                        "source": "response_status",
                        "value": 200
                    }
                ],
                "auth": {},
                "body": "",
                "form": {},
                "headers": {},
                "method": "GET",
                "note": "",
                "step_type": "request",
                "url": "https://yourapihere.com/",
                "id": "53f8e1fd-0989-491a-9f15-cc055f27d097",
                "variables": []
            }
        ],
        "trigger_url": "http://api.runscope.com/radar/b96ecee2-cce6-4d80-8f07-33ac22a22ebd/trigger",
        "id": "626a024c-f75e-4f57-82d4-104fe443c0f3"
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}

The following parameters can be set on the request step, and these are formatted the same as the test detail response output.

Attributes

• step_type string

  Always set to request

• method string

  The HTTP method for this request step

• url string

  The URL to make a request to for this step. This may contain both query string parameters and variables

• body string

  A string to use as the body of the request

• assertions array

  A list of assertions to apply to the HTTP response from this request

  Show/Hide Child Attributes

  • source string

    The source where the assertion is being run against

  • comparison string

    The comparison value that was used

  • value integer

    The value that was used in the comparison

• variables array

  A list of variables to extract out of the HTTP response from this request

  Show/Hide Child Attributes

  • name string

    The name of the variable

  • property string

    The property where the value for this variable is being pulled from

  • source string

    The data source for the variable. Possible values are json, xml, response_headers, response_size_bytes, response_time_ms or status_code

• auth object

  An authentication object with either basic, OAuth 1.0, OAuth 2.0 or client certificate credentials for authenticating this request

  Show/Hide Basic authentication

  • password string

    Password for this authentication

  • username string

    User name for this authentication

  • auth_type string

    The authorization type for this authentication. Value is basic

  Show/Hide OAuth 1.0

  • consumer_key string

    The Consumer Key used for asking the service for authorization

  • consumer_secret string

    The Consumer Secret used for asking the service for authorization

  • access_token string

    The token used for accessing the resource

  • token_secret string

    The secret that accompanies the access token

  • signature_type string

    Signature type. Value can be auth_header, query, or body

  • auth_type string

    The authorization type for this authentication. Value is oauth_1

  Show/Hide OAuth 2.0 (short)

  • access_token string

    Value of the access token

  • token_location string

    Location of the token. Value can be query or auth_header

  • auth_type string

    The authorization type for this authentication. Value is oauth_2

  Show/Hide OAuth 2.0 (extended)

  • Note: Not all parameters are mandatory. Only the parameters included in the payload are saved in the test Environment or Template. Parameters not included in the payload will show as "null" in the response.

  • grant_type string

    OAuth 2.0 grant type. Value can be authorization_code, authorization_code_pkce, implicit, password_credentials, or client_credentials

    Important! For Authorization Code, Authorization Code with PKCE, and Implicit grant types, you must add or register the API Monitoring Redirect URI, https://www.runscope.com/oauth2/callback, to the third-party authorization site. See Redirect URI Registration for details.

  • access_token string

    Value of the access token

  • token_location string

    Location of the token. Value can be query or auth_header

  • auth_url string

    Third-party authorization URL

  • access_token_url string

    URL for the access token

  • client_id string

    The ID of the client

  • client_secret string

    The client secret

  • code_challenge_method string

    Method for challenging code, either plain or S256. For PKCE grant type only. Default is SHA-256

  • code_verifier string

    The code verifier string generated by the app, if available. For PKCE grant type only

  • password string

    Password for third-party authorization

  • username string

    User name for third-party authorization

  • scope string

    The OAuth 2.0 scope string, if used

  • state string

    The OAuth 2.0 state string, if used

  • client_authentication string

    Method of client authentication, either either sent in basic_auth_header or body. Default is basic_auth_header

  • auth_type string

    The authorization type for this authentication. Value is oauth_2

  • refresh_token string

    Value of the refresh token

  • is_auto_refresh_token boolean

    Determines whether the refresh token is auto-generated

• headers object

  An object with keys as header names matched to their values. Values can either be a single string or an array of strings

  Show/Hide Child Attributes

  • headerName array

    The header name of this header (i.e. Accept) and it's list of values for this header name (i.e. */*)

• form object

  An object with keys as form post parameter names matched to their values. Values can either be a single string or an array of strings

• scripts array

  A list of post-response scripts to run after this request

• before_scripts array

  A list of pre-request scripts to run before this request

• note string

  A description or note for this request step

• skipped boolean

  If this is set to true, this step will be skipped when the test is executed

Pause Step

Adding Pause Step

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/steps' \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"step_type": "pause","duration": 5}'

The POST body must be a JSON object.

Adding Pause Steps Request Attributes

The following parameters can be set on the pause step, and these are formatted the same as the test detail response output.

Attributes

• step_type string

  Always set to pause

• duration integer

  This is the duration of the pause step in seconds. It must be an integer between 1 and 120

Condition Step

Adding Condition Step

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/steps' \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"step_type":"condition","left_value":"{{user_id}}","comparison":"equal","right_value":"12345","steps": [{"assertions": [{"comparison":"equal_number","source":"response_status","value": 200}],"method":"GET","step_type":"request","url":"https://yourapihere.com/"}]}'

The POST body must be a JSON object.

Adding Condition Steps Request Attributes

The following JSON sample provides a more readable version of the content contained in the above curl example. This example represents the attributes and values contained in the -d flag of the curl example.

Adding Condition Step Sample POST Body(JSON) for Condition Step

{
    "step_type": "condition",
    "left_value": "{{user_id}}",
    "comparison": "equal",
    "right_value": "12345",
    "steps": [
        {
            "assertions": [
                {
                    "comparison": "equal_number",
                    "source": "response_status",
                    "value": 200
                }
            ],
            "method": "GET",
            "step_type": "request",
            "url": "https://yourapihere.com/"
        }
    ]
}

Response 201 CREATED

{
    "data": {
        "created_at": 1438832081,
        "created_by": {
            "email": "grace@example.com",
            "name": "Grace Hopper",
            "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"
        },
        "default_environment_id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
        "description": null,
        "environments": [
            {
                "emails": {
                    "notify_all": false,
                    "notify_on": "all",
                    "notify_threshold": 1,
                    "recipients": []
                },
                "initial_variables": {
                    "base_url": "https://api.example.com"
                },
                "integrations": [
                    {
                        "description": "Pagerduty Account",
                        "integration_type": "pagerduty",
                        "id": "53776d9a-4f34-4f1f-9gff-c155dfb6692e"
                    }
                ],
                "name": "Test Settings",
                "parent_environment_id": null,
                "preserve_cookies": false,
                "regions": [
                    "us1"
                ],
                "remote_agents": [],
                "script": "",
                "test_id": "626a024c-f75e-4f57-82d4-104fe443c0f3",
                "id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
                "verify_ssl": true,
                "webhooks": null
            }
        ],
        "last_run": null,
        "name": "Sample Name",
        "schedules": [],
        "steps": [
            {
                "assertions": [
                    {
                        "comparison": "equal_number",
                        "source": "response_status",
                        "value": 200
                    }
                ],
                "method": "GET",
                "step_type": "request",
                "url": "https://yourapihere.com/"
            }
        ],
        "trigger_url": "http://api.runscope.com/radar/b96ecee2-cce6-4d80-8f07-33ac22a22ebd/trigger",
        "id": "626a024c-f75e-4f57-82d4-104fe443c0f3"
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}

The following parameters can be set on the condition step, and these are formatted the same as the test detail response output.

Attributes

• step_type string

  Always set to condition

• left_value string

  The left hand value of the assertion

• comparison string

  An assertion comparison to determine whether or not to execute the embedded steps

• right_value string

  The right-hand side value of the assertion, if one is required

• steps array

  An array of test steps to execute if the comparison evaluates successfully

Ghost Inspector Step

Adding Ghost Inspector Step

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/steps' \
    -X POST \
    -H 'Content-Type: application/json' \
    -d '{"step_type":"ghost-inspector","integration_id":"c6f2aa66-ed7e-4faf-a05d-5da7416da3ee","suite_id":"55c3b3b3fdac93101d808ca5","test_id":"55c3b3dbfdac93101d808ca6","is_custom_start_url": false,"start_url":"http://example.com","assertions": [{"comparison":"equal","property":"data.passing","source":"response_json","value":"true"}],"variables": [{"name":"screenshot_url","property":"data.screenshot.small.defaultUrl","source":"response_json"}]}'

The POST body must be a JSON object.

Adding Ghost Inspector Steps Data Attributes

The following JSON sample provides a more readable version of the content contained in the above curl example. This example represents the attributes and values contained in the -d flag of the curl example.

Adding Ghost Inspector Step Sample POST Body(JSON) for Ghost Inspector Step

{
    "step_type": "ghost-inspector",
    "integration_id": "c6f2aa66-ed7e-4faf-a05d-5da7416da3ee",
    "suite_id": "55c3b3b3fdac93101d808ca5",
    "test_id": "55c3b3dbfdac93101d808ca6",
    "is_custom_start_url": false,
    "start_url": "http://example.com",
    "assertions": [
        {
            "comparison": "equal",
            "property": "data.passing",
            "source": "response_json",
            "value": "true"
        }
    ],
    "variables": [
        {
            "name": "screenshot_url",
            "property": "data.screenshot.small.defaultUrl",
            "source": "response_json"
        }
    ]
}

Response 201 CREATED

{
    "data": {
        "created_at": 1438832081,
        "created_by": {
            "email": "grace@example.com",
            "name": "Grace Hopper",
            "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"
        },
        "default_environment_id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
        "description": null,
        "environments": [
            {
                "emails": {
                    "notify_all": false,
                    "notify_on": "all",
                    "notify_threshold": 1,
                    "recipients": []
                },
                "initial_variables": {
                    "base_url": "https://api.example.com"
                },
                "integrations": [
                    {
                        "description": "Pagerduty Account",
                        "integration_type": "pagerduty",
                        "id": "53776d9a-4f34-4f1f-9gff-c155dfb6692e"
                    }
                ],
                "name": "Test Settings",
                "parent_environment_id": null,
                "preserve_cookies": false,
                "regions": [
                    "us1"
                ],
                "remote_agents": [],
                "script": "",
                "test_id": "626a024c-f75e-4f57-82d4-104fe443c0f3",
                "id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
                "verify_ssl": true,
                "webhooks": null
            }
        ],
        "last_run": null,
        "name": "Sample Name",
        "schedules": [],
        "steps": [
            {
                "step_type": "ghost-inspector",
                "integration_id": "c6f2aa66-ed7e-4faf-a05d-5da7416da3ee",
                "suite_id": "55c3b3b3fdac93101d808ca5",
                "test_id": "55c3b3dbfdac93101d808ca6",
                "is_custom_start_url": false,
                "start_url": "http://example.com",
                "assertions": [
                    {
                        "comparison": "equal",
                        "property": "data.passing",
                        "source": "response_json",
                        "value": "true"
                    }
                ],
                "variables": [
                    {
                        "name": "screenshot_url",
                        "property": "data.screenshot.small.defaultUrl",
                        "source": "response_json"
                    }
                ]
            }
        ],
        "trigger_url": "http://api.runscope.com/radar/b96ecee2-cce6-4d80-8f07-33ac22a22ebd/trigger",
        "id": "626a024c-f75e-4f57-82d4-104fe443c0f3"
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}

The following parameters can be set on the ghost inspector step, and these are formatted the same as the test detail response output.

Attributes

• step_type string

  Always set to ghost-inspector

• integration_id string

  The id of an account integration with Ghost Inspector as found in the team integrations list

• suite_id string

  The Ghost Inspector suite id of the test to run. You can find this in the Ghost Inspector API

• test_id string

  The Ghost Inspector test id of the test to run. You can find this in the Ghost Inspector API

• is_custom_start_url boolean

• start_url string

  A custom Start URL for the Ghost Inspector test to execute with

• assertions array

  A list of assertions to apply to the incoming webhook result from Ghost Inspector

• variables array

  A list of variables to extract out of the incoming webhook result from Ghost Inspector

Subtest Step

Adding Subtest Step

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/steps' \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"step_type":"request","method":"POST","url":"https://yourapihere.com/example/path","body":"{ \"hello\": \"world\" }",assertions": [{"source":"response_status","comparison":"equal_number","value": 200}],"variables":[{"name":"source_ip","property":"origin","source":"response_json"}],"auth": {"username":"authBasicUsername","auth_type":"basic","password":"authBasicPassword"},"headers": {"Content-Type": ["application/json"],"Accept": [*/*"]},"scripts": ["log(\"This is a sample post-response script\");","log(\"This is a second sample post-response script\");"],"before_scripts": ["log(\"This is a sample pre-request script\");","log(\"This is a second sample pre-request script\");"],"note":"get example data"}'

The POST body must be a JSON object.

Adding Subtest Steps Data Attributes

The following JSON sample provides a more readable version of the content contained in the above curl example. This example represents the attributes and values contained in the -d flag of the curl example.

Adding Subtest Step Sample POST Body(JSON) for Subtest Step

{
    "step_type": "subtest",
    "test_uuid": "c6f2aa66-ed7e-4faf-a05d-5da7416da3ee",
    "environment_uuid": "d6f2aa66-ed7e-4faf-a05d-5da7416da3ef",
    "bucket_key": "fd1qy7w2l7ka",
    "assertions": [
        {
            "source": "response_status",
            "comparison": "equal_number",
            "value": 200
        }
    ],
    "variables": [
        {
            "name": "regionRunFrom",
            "property": "region",
            "source": "response_json"
        }    
    ],
    "params": [
        {
            "name": "foo",
            "value": "{{bar}}"
        }
    ]
}

Response 201 CREATED

{
    "data": {
        "created_at": 1438832081,
        "created_by": {
            "email": "grace@example.com",
            "name": "Grace Hopper",
            "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"
        },
        "default_environment_id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
        "description": null,
        "environments": [
            {
                "emails": {
                    "notify_all": false,
                    "notify_on": "all",
                    "notify_threshold": 1,
                    "recipients": []
                },
                "initial_variables": {
                    "base_url": "https://api.example.com"
                },
                "integrations": [
                    {
                        "description": "Pagerduty Account",
                        "integration_type": "pagerduty",
                        "id": "53776d9a-4f34-4f1f-9gff-c155dfb6692e"
                    }
                ],
                "name": "Test Settings",
                "parent_environment_id": null,
                "preserve_cookies": false,
                "regions": [
                    "us1"
                ],
                "remote_agents": [],
                "script": "",
                "test_id": "626a024c-f75e-4f57-82d4-104fe443c0f3",
                "id": "a50b63cc-c377-4823-9a95-8b91f12326f2",
                "verify_ssl": true,
                "webhooks": null
            }
        ],
        "last_run": null,
        "name": "Sample Name",
        "schedules": [],
        "steps": [
            {
                "step_type": "subtest",
                "test_uuid": "c6f2aa66-ed7e-4faf-a05d-5da7416da3ee",
                "environment_uuid": "d6f2aa66-ed7e-4faf-a05d-5da7416da3ef",
                "bucket_key": "fd1qy7w2l7ka",
                "assertions": [
                    {
                        "source": "response_status",
                        "comparison": "equal_number",
                        "value": 200,
                    }
                ],
                "variables": [
                    {
                        "name": "regionRunFrom",
                        "property": "region",
                        "source": "response_json",
                    }    
                ],
                "params": [
                    {
                        "name": "foo",
                        "value": "{{bar}}",
                    }
                ]
            }
        ],
        "trigger_url": "http://api.runscope.com/radar/b96ecee2-cce6-4d80-8f07-33ac22a22ebd/trigger",
        "id": "626a024c-f75e-4f57-82d4-104fe443c0f3"
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}

The following parameters can be set on the subtest step, and these are formatted the same as the test detail response output.

Attributes

• step_type string

  Always set to subtest

• test_uuid string

  The embedded test's unique id

• environment_uuid string

  The environment uuid to run with the subtest

• bucket_key string

  The bucket key to which the subtest belongs

• assertions array

  A list of assertions to apply to the incoming subtest result

• variables array

  A list of variables to extract out of the incoming subtest result

• params array

  A list of key value pairs to pass to the subtest at runtime. This is a way to pass variables extracted in the parent test to the subtest

Defining Assertions

Defining Assertions for Status Code

Defining Assertion for Status Code Sample POST Body(JSON) for Status Code == 200

"assertions": [
    {
        "source": "response_status", 
        "comparison": "equal_number", 
        "value": 200
    }
]

Defining Assertions for Element Contains Text

Defining Assertion for Element Contians Text Sample POST Body(JSON) for JSON element 'address' contains the text "avenue"

"assertions": [
    {
        "source": "response_json", 
        "property": "address", 
        "comparison": "contains", 
        "value": "avenue"
    }
]

Defining Assertions for Response Time

Defining Assertions for Response Time Sample POST Body(JSON) for Response Time is faster than 1 second.

"assertions": [
    {
        "source": "response_time", 
        "comparison": "is_less_than", 
        "value": 1000
    }
]

Assertions allow you to specify success criteria for a given request, Ghost Inspector, subtest, or condition step. Each assertion is defined by a source, property, comparison, and value.

Assertion Sources List

Sources

• response_status

  Assert on the value of the HTTP status code from the Response

• response_headers

  Assert on the value of a Response Header. You must include a Property with the header name to assert on

• response_json

  Parse the response body as JSON. You must include a Property with the JSON path to assert on

• response_xml

  Parse the response body as XML. You must include a Property with the XPath to assert on

• response_text

  Parse the response body as plain text. This source does not specify a Property

• response_time

  Assert on the execution time of the response in milliseconds

• response_size

  Assert on the size of the Response body in bytes

Assertion Comparisons List

Comparisons

• equal

  A string equality check on the given property and value

• empty

  The given value is an empty string

• not_empty

  The given value is not an empty string

• not_equal

  The given string property is not equal to the given string value

• contains

  The given string value is found in the given property

• does_not_contain

  The given string value is not found in the given property

• is_a_number

  The source property can be converted to a numeric value. This comparison does not take a value

• equal_number

  The source property is numerically equal to the given value. This comparison ensures the values are able to be converted to numbers

• is_less_than

  The given property is numerically less than the given value

• is_less_than_or_equal

  The given property is numerically less than or equal to the given value

• is_greater_than

  The given property is numerically greater than the given value

• is_greater_than_or_equal

  The given property is numerically greater than or equal to the given value

• has_key

  The JSON property evaluates to an object and contains the given value as a key. Source must be response_json

• has_value

  The JSON property evaluates to an array and contains the given value as an element. Source must be response_json

• is_null

  The JSON property has a NULL value. Source must be response_json

Defining Variables

Defining Variables

Defining Variables Sample POST Body(JSON) to set {{myUserId}} to the value of JSON element 'user_id'

"variables": [
    {
        "source": "response_json", 
        "property": "user_id", 
        "name": "myUserId"
    }
]

Variables allow you to extract data from request, subtest, and Ghost Inspector steps for use in subsequent steps in the test. Similar to Assertions, each variable is defined by a name, source, and property.

Variable Sources List

Sources

• response_status

  Create a variable from the value of the HTTP status code from the Response

• response_headers

  Create a variable from the value of a Response Header. You must include a property with the name of the header to extract the value from

• response_json

  Parse the response body as JSON. You must include a property with the JSON path to extract

• response_xml

  Parse the response body as XML. You must include a property with the XPath to extract

• response_text

  Parse the response body as plain text. This source does not specify a property

• response_time

  Create a variable from the execution time of the response in milliseconds

• response_size

  Create a variable from the size of the Response body in bytes

Defining Authentication

Defining Authentication with Basic Auth

Defining Authentication with Basic Auth Sample POST Body(JSON) with Basic Auth

"auth": {
        "auth_type": "basic",
        "username": "authBasicUsername",
        "password": "authBasicPassword"
}

Defining Authentication with OAuth 1.0

Defining Authentication with OAuth 1.0 Sample POST Body(JSON) with OAuth 1.0 with signature type set to Authorization header. Other accepted values for signature_type are: body and query

"auth": {
        "auth_type": "oauth_1",
        "access_token": "accessToken",
        "consumer_secret": "consumerSecret",
        "signature_type": "auth_header",
        "consumer_key": "consumerKey",
        "token_secret": "tokenSecret"
}

Defining Authentication with Client Certificate

Defining Authentication with Client Certificate Sample POST Body(JSON) to set {{myUserId}} with Client Certificate auth

"auth": {
        "auth_type": "client_certificate"
}

The authentication property allows you to define the authentication method for your requests. We currently support Basic, OAuth 1.0a, and Client Certificate. If you want to use OAuth2, we recommend using subtest steps, and you can find more information about it in this blog post. The type of authentication is defined in the auth_type property, and each method requires different properties. You can find them in these following examples.

Changing Step Order

Changing Step Order

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/steps' \
    -X PUT
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '["f6b09ca8-0803-478f-9919-d4ddc66db006","839a5dff-dad3-4693-90a3-dcaba462514a"]'

The following JSON sample provides a more readable version of the content contained in the above curl example. This example represents the attributes and values contained in the -d flag of the curl example.

Changing Step Order Sample POST Body(JSON) for Changing Step Order

[
    "f6b09ca8-0803-478f-9919-d4ddc66db006",
    "839a5dff-dad3-4693-90a3-dcaba462514a"
]

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/steps' \
    -X PUT
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '["f6b09ca8-0803-478f-9919-d4ddc66db006",{"id":"c6f2aa66-ed7e-4faf-a05d-5da7416da3ee","steps":["53f8e1fd-0989-491a-9f15-cc055f27d097","626a024c-f75e-4f57-82d4-104fe443c0f3"]},"839a5dff-dad3-4693-90a3-dcaba462514a"]'

The following JSON sample provides a more readable version of the content contained in the above curl example. This example represents the attributes and values contained in the -d flag of the curl example.

Changing Step Order with Condition Sample PUT Body(JSON) for Changing Step Order with Condition

[
    "f6b09ca8-0803-478f-9919-d4ddc66db006",
    {
        "id": "c6f2aa66-ed7e-4faf-a05d-5da7416da3ee",
        "steps": [
            "53f8e1fd-0989-491a-9f15-cc055f27d097",
            "626a024c-f75e-4f57-82d4-104fe443c0f3"
        ]
    },
    "839a5dff-dad3-4693-90a3-dcaba462514a"
]

The body of the PUT request should contain an ordered list of id's of the test step for the test. If any id's are omitted the request will fail. If the test contains a Condition, you must provide the step and its embedded steps in the form of an object like:
{ "id": "your_condition_id", "steps": ["your_embeded_step_id_1",...]}

Test Step Detail

Changing Step Order

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/steps/<step_id>' \
    -H 'Authorization: Bearer <access_token>'

Response 200 OK

{
    "data": {
        "assertions": [
            {
                "comparison": "is_null",
                "source": "response_json"
            }
        ],
        "auth": {},
        "body": "",
        "form": {},
        "headers": {},
        "method": "GET",
        "note": "this is step 1",
        "step_type": "request",
        "url": "https://yourapihere.com/",
        "id": "f6b09ca8-0803-478f-9919-d4ddc66db006",
        "variables": []
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}

Get the details of a single test step for a given API test.

Modifying Test Steps

Modifying Test Steps

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/steps/<step_id>' \
    -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"method":"GET","url":"https://yourapihere.com/example/path","assertions": [{"source":"response_status","comparison":"equal_number","value": 200}],"variables": [{"name":"source_ip","property":"origin","source":"response_json"}],"note":"get example data"}'

The same JSON Body for adding a Test Step can be used to modify an existing step.

The following JSON sample provides a more readable version of the content contained in the above curl example. This example represents the attributes and values contained in the -d flag of the curl example.

Modifying Test Steps Sample POST Body(JSON) for Modifying Test Steps

{ 
    "method": "GET",
    "url": "https://yourapihere.com/example/path",
    "assertions": [
        {
            "source": "response_status", 
            "comparison": "equal_number", 
            "value": 200
        }
    ],
    "variables": [
        {
            "name": "source_ip",
            "property": "origin",
            "source": "response_json"
        }    
    ],
    "note": "get example data"
}

Update the details of a single test step for a given API test.

Delete Test Step

Delete Test Step

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/steps/<step_id>' \
    -X DELETE \
    -H 'Authorization: Bearer <access_token>'

Response 204 NO CONTENT

Delete a step from a test.

Environments

Retrieve details for shared and test-specific environments.

Test Environment List

Test Environment List

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/environments' \
    -H 'Authorization: Bearer <access_token>'

Get the details of the environments for a test.

Test Environment List Response Attributes

Response 200 OK

{
    "auth": {
        "password": "password",
        "username": "username",
        "auth_type": "basic"
    },
    "emails": {
        "notify_all": false,
        "notify_on": "all",
        "notify_threshold": null,
        "recipients": [
            {
                "email": "grace@example.com",
                "name": "Grace Hopper",
                "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"
            }
        ]
    },
    "initial_variables": {
        "my_variable": "some value",
        "one more": "values"
    },
    "integrations": [],
    "name": "Remote Settings",
    "parent_environment_id": null,
    "preserve_cookies": false,
    "regions": [
        "us1",
        "jp1"
    ],
    "retry_on_failure": false,
    "stop_on_failure": false,
    "remote_agents": [
        {
            "name": "my-local-machine.runscope.com",
            "uuid": "141d4dbc-1e41-401e-8067-6df18501e9ed"
        }
    ],
    "script": "var a = \"asdf\";\nlog(\"OK\");",
    "test_id": null,
    "id": "f8007150-0052-482c-9d52-c3ea4042e0f5",
    "verify_ssl": true,
    "client_certificate": "",
    "webhooks": [
        "http://api.example.com/webhook_reciever",
        "https://yourapihere.com/post"
    ]
}

Attributes

• auth object

  The authentication settings for the test environment. Basic, OAuth 1.0, and short and extended OAuth 2.0 methods are supported.

  Show/Hide Basic authentication

  • password string

    Password for this authentication

  • username string

    User name for this authentication

  • auth_type string

    The authorization type for this authentication. Value is basic

  Show/Hide OAuth 1.0

  • consumer_key string

    The Consumer Key used for asking the service for authorization

  • consumer_secret string

    The Consumer Secret used for asking the service for authorization

  • access_token string

    The token used for accessing the resource

  • token_secret string

    The secret that accompanies the access token

  • signature_type string

    Signature type. Value can be auth_header, query, or body

  • auth_type string

    The authorization type for this authentication. Value is oauth_1

  Show/Hide OAuth 2.0 (short)

  • access_token string

    Value of the access token

  • token_location string

    Location of the token. Value can be query or auth_header

  • auth_type string

    The authorization type for this authentication. Value is oauth_2

  Show/Hide OAuth 2.0 (extended)

  • Note: Not all parameters are mandatory. Only the parameters included in the payload are saved in the test Environment or Template. Parameters not included in the payload will show as "null" in the response.

  • grant_type string

    OAuth 2.0 grant type. Value can be authorization_code, authorization_code_pkce, implicit, password_credentials, or client_credentials

    Important! For Authorization Code, Authorization Code with PKCE, and Implicit grant types, you must add or register the API Monitoring Redirect URI, https://www.runscope.com/oauth2/callback, to the third-party authorization site. See Redirect URI Registration for details.

  • access_token string

    Value of the access token

  • token_location string

    Location of the token. Value can be query or auth_header

  • auth_url string

    Third-party authorization URL

  • access_token_url string

    URL for the access token

  • client_id string

    The ID of the client

  • client_secret string

    The client secret

  • code_challenge_method string

    Method for challenging code, either plain or S256. For PKCE grant type only. Default is SHA-256

  • code_verifier string

    The code verifier string generated by the app, if available. For PKCE grant type only

  • password string

    Password for third-party authorization

  • username string

    User name for third-party authorization

  • scope string

    The OAuth 2.0 scope string, if used

  • state string

    The OAuth 2.0 state string, if used

  • client_authentication string

    Method of client authentication, either either sent in basic_auth_header or body. Default is basic_auth_header

  • auth_type string

    The authorization type for this authentication. Value is oauth_2

  • refresh_token string

    Value of the refresh token

  • is_auto_refresh_token boolean

    Determines whether the refresh token is auto-generated

• emails object

  The email details for sending notifications for this test

  Show/Hide Child Attributes

  • notify_all boolean

    Send an email to all team members according to the notify_on rules

  • notify_on string

    Upon completion of a test run Runscope will send email notifications according to the following rules:
    

    • all — send an email for every test run completed
    • failures — send an email for every test run that fails
    • threshold — send an email only after notify_threshold failures
    • switch — send an email only after notify_threshold failures, and then once more when it begins passing again.

  • notify_threshold null

    An integer between 1 and 10 for use with the notify_on settings: threshold and switch

  • recipients array

    A list of team users to recieve emails according to the other settings

    Show/Hide Child Attributes

    • email string

      The email of the user

    • name string

      The name of the user

    • id string

      The unique identifier of the user

• initial_variables object

  An object with the keys and values being used for variables when the test begins

  Show/Hide Child Attributes

  • variableName string

    The key contains the variable name (i.e. variableName) and the value is the value of the variable (i.e. some value)

• integrations array

  A list of integrations to enable for test runs using this environment

• name string

  The name for this environment

• parent_environment_id null

  The parent environment to inherit from, applies only to test-specific environments

• preserve_cookies boolean

  If this is set to true, tests using this environment will manage cookies between steps

• regions array

  A list of Runscope regions to execute test runs in when using this environment

• retry_on_failure boolean

  If this is set to true, an additional test run will be triggered immediately after a failed scheduled test run

• stop_on_failure boolean

  If this is set to true, test runs will stop executing after the first step that fails. All subsequent steps will be skipped

• remote_agents array

  A list of remote agents to execute test runs in when using this environment

  Show/Hide Child Attributes

  • name string

    The name of the remote agent

  • uuid string

    The unique identifier for the remote agent

• script string

  The initial script to run before starting tests using this environment

• test_id string

  The test this environment is associated with, applies only to test-specific environments

• id string

  The unique ID for this environment

• verify_ssl boolean

  If this is set to false, tests using this environment won't verify SSL certificates

• client_certificate string

  Client certificate text available to be used in request authentication. PEM-encoded

• webhooks array

  A list of URL's to send results to when test runs using this environment finish

Create Test Environment

Create Test Environment

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/environments' \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"auth": {"password":"password","username":"username","auth_type":"basic"},"emails": {"notify_all": false,"notify_on":"all","notify_threshold": null,"recipients": [{"email":"grace@example.com","name":"Grace Hopper","id":"4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"}]},"initial_variables": {"my_variable":"some value","one more":"values"},"integrations": [],"name":"Remote Settings","parent_environment_id": null,"preserve_cookies": false,"regions": ["us1","jp1"],"retry_on_failure": false,"stop_on_failure": false,"remote_agents": [{"name":"my-local-machine.runscope.com","uuid":"141d4dbc-1e41-401e-8067-6df18501e9ed"}],"script":"var a = \"asdf\";\nlog(\"OK\");","verify_ssl": true,"client_certificate":"","webhooks": ["http://api.example.com/webhook_reciever","https://yourapihere.com/post"]}'

The following JSON sample provides a more readable version of the content contained in the above curl example. This example represents the attributes and values contained in the -d flag of the curl example.

Create Test Environment Sample POST Body(JSON) for Create Test Environment

{
    "auth": {
        "password": "password",
        "username": "username",
        "auth_type": "basic"
    },
    "emails": {
        "notify_all": false,
        "notify_on": "all",
        "notify_threshold": null,
        "recipients": [
            {
                "email": "grace@example.com",
                "name": "Grace Hopper",
                "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"
            }
        ]
    },
    "initial_variables": {
        "my_variable": "some value",
        "one more": "values"
    },
    "integrations": [],
    "name": "Remote Settings",
    "parent_environment_id": null,
    "preserve_cookies": false,
    "regions": [
        "us1",
        "jp1"
    ],
    "retry_on_failure": false,
    "stop_on_failure": false,
    "remote_agents": [
        {
            "name": "my-local-machine.runscope.com",
            "uuid": "141d4dbc-1e41-401e-8067-6df18501e9ed"
        }
    ],
    "script": "var a = \"asdf\";\nlog(\"OK\");",
    "verify_ssl": true,
    "client_certificate": "",
    "webhooks": [
        "http://api.example.com/webhook_reciever",
        "https://yourapihere.com/post"
    ]
}

Response 201 CREATED

{
    "auth": {
        "password": "password",
        "username": "username",
        "auth_type": "basic"
    },
    "emails": {
        "notify_all": false,
        "notify_on": "all",
        "notify_threshold": null,
        "recipients": [
            {
                "email": "grace@example.com",
                "name": "Grace Hopper",
                "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"
            }
        ]
    },
    "initial_variables": {
        "my_variable": "some value",
        "one more": "values"
    },
    "integrations": [],
    "name": "Remote Settings",
    "parent_environment_id": null,
    "preserve_cookies": false,
    "regions": [
        "us1",
        "jp1"
    ],
    "retry_on_failure": false,
    "stop_on_failure": false,
    "remote_agents": [
        {
            "name": "my-local-machine.runscope.com",
            "uuid": "141d4dbc-1e41-401e-8067-6df18501e9ed"
        }
    ],
    "script": "var a = \"asdf\";\nlog(\"OK\");",
    "test_id": null,
    "id": "f8007150-0052-482c-9d52-c3ea4042e0f5",
    "verify_ssl": true,
    "client_certificate": "",
    "webhooks": [
        "http://api.example.com/webhook_reciever",
        "https://yourapihere.com/post"
    ]
}

Create a new test environment by POSTing a JSON body with the environment details.

Note: There is a limit of 100 local (test-specific) environments per bucket. The API call will fail once the limit is exceeded.

Shared Environment List

Test Environment List

curl 'https://api.runscope.com/buckets/<bucket_key>/environments' \
    -H 'Authorization: Bearer <access_token>'

Response 200 OK

{
    "auth": {
        "password": "password",
        "username": "username",
        "auth_type": "basic"
    },
    "emails": {
        "notify_all": false,
        "notify_on": "all",
        "notify_threshold": null,
        "recipients": [
            {
                "email": "grace@example.com",
                "name": "Grace Hopper",
                "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"
            }
        ]
    },
    "initial_variables": {
        "my_variable": "some value",
        "one more": "values"
    },
    "integrations": [],
    "name": "Remote Settings",
    "parent_environment_id": null,
    "preserve_cookies": false,
    "regions": [
        "us1",
        "jp1"
    ],
    "retry_on_failure": false,
    "stop_on_failure": false,
    "remote_agents": [
        {
            "name": "my-local-machine.runscope.com",
            "uuid": "141d4dbc-1e41-401e-8067-6df18501e9ed"
        }
    ],
    "script": "var a = \"asdf\";\nlog(\"OK\");",
    "test_id": null,
    "id": "f8007150-0052-482c-9d52-c3ea4042e0f5",
    "verify_ssl": true,
    "client_certificate": "",
    "webhooks": [
        "http://api.example.com/webhook_reciever",
        "https://yourapihere.com/post"
    ]
}

Get the details of the shared environments for a bucket.

Create Shared Environment

Create Test Environment

curl 'https://api.runscope.com/buckets/<bucket_key>/environments' \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"auth": {"password":"password","username":"username","auth_type":"basic"},"emails": {"notify_all": false,"notify_on":"all","notify_threshold": null,"recipients": [{"email":"grace@example.com","name":"Grace Hopper","id":"4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"}]},"initial_variables": {"my_variable":"some value","one more":"values"},"integrations": [],"name":"Remote Settings","parent_environment_id": null,"preserve_cookies": false,"regions": ["us1","jp1"],"retry_on_failure": false,"stop_on_failure": false,"remote_agents": [{"name":"my-local-machine.runscope.com","uuid":"141d4dbc-1e41-401e-8067-6df18501e9ed"}],"script":"var a = \"asdf\";\nlog(\"OK\");","verify_ssl": true,"client_certificate":"","webhooks": ["http://api.example.com/webhook_reciever","https://yourapihere.com/post"]}'

The following JSON sample provides a more readable version of the content contained in the above curl example. This example represents the attributes and values contained in the -d flag of the curl example. See the example POST body for creating a Test Environment.

Create Test Environment Sample POST Body(JSON) for Create Test Environment

{
    "auth": {
        "password": "password",
        "username": "username",
        "auth_type": "basic"
    },
    "emails": {
        "notify_all": false,
        "notify_on": "all",
        "notify_threshold": null,
        "recipients": [
            {
                "email": "grace@example.com",
                "name": "Grace Hopper",
                "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"
            }
        ]
    },
    "initial_variables": {
        "my_variable": "some value",
        "one more": "values"
    },
    "integrations": [],
    "name": "Remote Settings",
    "parent_environment_id": null,
    "preserve_cookies": false,
    "regions": [
        "us1",
        "jp1"
    ],
    "retry_on_failure": false,
    "stop_on_failure": false,
    "remote_agents": [
        {
            "name": "my-local-machine.runscope.com",
            "uuid": "141d4dbc-1e41-401e-8067-6df18501e9ed"
        }
    ],
    "script": "var a = \"asdf\";\nlog(\"OK\");",
    "verify_ssl": true,
    "client_certificate": "",
    "webhooks": [
        "http://api.example.com/webhook_reciever",
        "https://yourapihere.com/post"
    ]
}

Response 201 CREATED

{
    "auth": {
        "password": "password",
        "username": "username",
        "auth_type": "basic"
    },
    "emails": {
        "notify_all": false,
        "notify_on": "all",
        "notify_threshold": null,
        "recipients": [
            {
                "email": "grace@example.com",
                "name": "Grace Hopper",
                "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"
            }
        ]
    },
    "initial_variables": {
        "my_variable": "some value",
        "one more": "values"
    },
    "integrations": [],
    "name": "Remote Settings",
    "parent_environment_id": null,
    "preserve_cookies": false,
    "regions": [
        "us1",
        "jp1"
    ],
    "retry_on_failure": false,
    "stop_on_failure": false,
    "remote_agents": [
        {
            "name": "my-local-machine.runscope.com",
            "uuid": "141d4dbc-1e41-401e-8067-6df18501e9ed"
        }
    ],
    "script": "var a = \"asdf\";\nlog(\"OK\");",
    "test_id": null,
    "id": "f8007150-0052-482c-9d52-c3ea4042e0f5",
    "verify_ssl": true,
    "client_certificate": "",
    "webhooks": [
        "http://api.example.com/webhook_reciever",
        "https://yourapihere.com/post"
    ]
}

Create a new test environment.

Note: There is a limit of 100 shared environments per bucket. The API call will fail once the limit is exceeded.

Environment Detail

Test Environment Detail

curl 'https://api.runscope.com/buckets/<bucket_key>/test/<test_id>/environments/<environment_id>' \
    -H 'Authorization: Bearer <access_token>'

Shared Environment Detail

curl 'https://api.runscope.com/buckets/<bucket_key>/environments/<environment_id>' \
    -H 'Authorization: Bearer <access_token>'

Response 200 OK

{
    "auth": {
        "password": "password",
        "username": "username",
        "auth_type": "basic"
    },
    "emails": {
        "notify_all": false,
        "notify_on": "all",
        "notify_threshold": null,
        "recipients": [
            {
                "email": "grace@example.com",
                "name": "Grace Hopper",
                "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"
            }
        ]
    },
    "initial_variables": {
        "my_variable": "some value",
        "one more": "values"
    },
    "integrations": [],
    "name": "Remote Settings",
    "parent_environment_id": null,
    "preserve_cookies": false,
    "regions": [
        "us1",
        "jp1"
    ],
    "retry_on_failure": false,
    "stop_on_failure": false,
    "remote_agents": [
        {
            "name": "my-local-machine.runscope.com",
            "uuid": "141d4dbc-1e41-401e-8067-6df18501e9ed"
        }
    ],
    "script": "var a = \"asdf\";\nlog(\"OK\");",
    "test_id": null,
    "id": "f8007150-0052-482c-9d52-c3ea4042e0f5",
    "verify_ssl": true,
    "client_certificate": "",
    "webhooks": [
        "http://api.example.com/webhook_reciever",
        "https://yourapihere.com/post"
    ]
}

Get the details of a single test environment or shared envionment.

Modify Environment

Modify Environment

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/environments/<environment_id>' \
    -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"auth": {"password":"password","username":"username","auth_type":"basic"},"emails": {"notify_all": false,"notify_on":"all","notify_threshold": null,"recipients": [{"email":"grace@example.com","name":"Grace Hopper","id":"4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"}]},"initial_variables": {"my_variable":"some value","one more":"values" },"integrations": [],"name":"Remote Settings","parent_environment_id": null,"preserve_cookies": false,"regions": ["us1","jp1"],"retry_on_failure": false,"stop_on_failure": false,"remote_agents": [{"name":"my-local-machine.runscope.com","uuid":"141d4dbc-1e41-401e-8067-6df18501e9ed"}],"script":"var a = \"asdf\";\nlog(\"OK\");","script_library": ["1a3eb343-4666-4056-bf3d-5e9693be86cd"],"verify_ssl": true,"client_certificate":"","webhooks": ["http://api.example.com/webhook_reciever","https://yourapihere.com/post"]}'

Modify Shared Environment

curl 'https://api.runscope.com/buckets/<bucket_key>/environments/<environment_id>' \
    -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"auth": {"password":"password","username":"username","auth_type":"basic"},"emails": {"notify_all": false,"notify_on":"all","notify_threshold": null,"recipients": [{"email":"grace@example.com","name":"Grace Hopper","id":"4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"}]},"initial_variables": {"my_variable":"some value","one more":"values" },"integrations": [],"name":"Remote Settings","parent_environment_id": null,"preserve_cookies": false,"regions": ["us1","jp1"],"retry_on_failure": false,"stop_on_failure": false,"remote_agents": [{"name":"my-local-machine.runscope.com","uuid":"141d4dbc-1e41-401e-8067-6df18501e9ed"}],"script":"var a = \"asdf\";\nlog(\"OK\");","script_library": ["1a3eb343-4666-4056-bf3d-5e9693be86cd"],"verify_ssl": true,"client_certificate":"","webhooks": ["http://api.example.com/webhook_reciever","https://yourapihere.com/post"]}'

The following JSON sample provides a more readable version of the content contained in the above curl example. This example represents the attributes and values contained in the -d flag of the curl example. See the example POST body for creating a Test Environment.

Modify Environment Sample PUT Body(JSON) for Modify Test Environment

{
    "auth": {
        "password": "password",
        "username": "username",
        "auth_type": "basic"
    },
    "emails": {
        "notify_all": false,
        "notify_on": "all",
        "notify_threshold": null,
        "recipients": [
            {
                "email": "grace@example.com",
                "name": "Grace Hopper",
                "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"
            }
        ]
    },
    "initial_variables": {
        "my_variable": "some value",
        "one more": "values"
    },
    "integrations": [],
    "name": "Remote Settings",
    "parent_environment_id": null,
    "preserve_cookies": false,
    "regions": [
        "us1",
        "jp1"
    ],
    "retry_on_failure": false,
    "stop_on_failure": false,
    "remote_agents": [
        {
            "name": "my-local-machine.runscope.com",
            "uuid": "141d4dbc-1e41-401e-8067-6df18501e9ed"
        }
    ],
    "script": "var a = \"asdf\";\nlog(\"OK\");",
    "script_library": [
        "1a3eb343-4666-4056-bf3d-5e9693be86cd"
    ],
    "verify_ssl": true,
    "client_certificate": "",
    "webhooks": [
        "http://api.example.com/webhook_reciever",
        "https://yourapihere.com/post"
    ]
}

Response 200 OK

{
    "auth": {
        "password": "password",
        "username": "username",
        "auth_type": "basic"
    },
    "emails": {
        "notify_all": false,
        "notify_on": "all",
        "notify_threshold": null,
        "recipients": [
            {
                "email": "grace@example.com",
                "name": "Grace Hopper",
                "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9"
            }
        ]
    },
    "initial_variables": {
        "my_variable": "some value",
        "one more": "values"
    },
    "integrations": [],
    "name": "Remote Settings",
    "parent_environment_id": null,
    "preserve_cookies": false,
    "regions": [
        "us1",
        "jp1"
    ],
    "retry_on_failure": false,
    "stop_on_failure": false,
    "remote_agents": [
        {
            "name": "my-local-machine.runscope.com",
            "uuid": "141d4dbc-1e41-401e-8067-6df18501e9ed"
        }
    ],
    "script": "var a = \"asdf\";\nlog(\"OK\");",
    "test_id": null,
    "id": "f8007150-0052-482c-9d52-c3ea4042e0f5",
    "verify_ssl": true,
    "client_certificate": "",
    "webhooks": [
        "http://api.example.com/webhook_reciever",
        "https://yourapihere.com/post"
    ]
}

Update the details of an test environment by making a PUT request with a JSON body of the environment details. The full environment details will need to be provided, not just the updated configuration.

Delete an Environment

Delete Environment

curl 'https://api.runscope.com/buckets/<bucket_key>/environments/<environment_id>' \
    -X DELETE \
    -H 'Authorization: Bearer <access_token>'

Response 204 NO CONTENT

Delete an environment.

Schedules

Retrieve and modify a test's schedules.

Test Schedule List

Test Schedule List

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/schedules' \
    -H 'Authorization: Bearer <access_token>'

Get the list of schedules for a test.

Test Schedule List Response Attributes

Response 200 OK

{
    "data": [
        {
            "environment_id": "1eeb3695-5d0f-467c-9d51-8b773dce29ba",
            "interval": "1h",
            "note": "Staging Environment",
            "id": "084e6df7-9165-46d2-9e1c-b87ccfc53d18"
        },
        {
            "environment_id": "5e70db57-7485-4ca9-bb4d-482416993ddd",
            "interval": "5m",
            "note": "Production Monitoring",
            "id": "c60e5a78-0dbd-493a-9e99-9a8282935d0c"
        }
    ],
    "error": null,
    "meta": {
        "status": "success"
    }
}

Attributes

• environment_id string

  The id of the environment to use when running the test

• interval string

  The schedule's interval, must be one of:
  

  • 1m — every minute
  • 5m — every 5 minutes
  • 15m — every 15 minutes
  • 30m — every 30 minutes
  • 1h — every hour
  • 6h — every 6 hours
  • 1d — every day

• note string

  A human-friendly description for the schedule

• id string

  The unique ID for this schedule

Schedule Details

Schedule Details

curl 'https://api.runscope.com/buckets/<bucket_key>/test/<test_id>/schedules/<schedule_id>' \
    -H 'Authorization: Bearer <access_token>'

Get the details of a single test schedule.

Schedule Details Response Attributes

Response 200 OK

{
    "data": {
            "environment_id": "1eeb3695-5d0f-467c-9d51-8b773dce29ba",
            "interval": "1h",
            "note": "Staging Environment",
            "id": "084e6df7-9165-46d2-9e1c-b87ccfc53d18"
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}

Attributes

• environment_id string

  required

  The id of the environment to use when running the test

• interval string

  required

  The schedule's interval (e.g. 1m, 5m, 15m, 30m, 1h, 6h, 1d)

• note string

  A human-friendly description for the schedule

Create Schedule

Create Schedule v1

curl 'https://api.runscope.com/v1/buckets/<bucket_key>/tests/<test_id>/schedules' \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"environment_id": "951b681e-0a16-44ab-acfb-505a0a8564e9","interval": "1d","note": "Once a day schedule"}'

Create Schedule v0

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/schedules' \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"environment_id": "951b681e-0a16-44ab-acfb-505a0a8564e9","interval": "1d","note": "Once a day schedule"}'

Create one or more tests in this bucket.

Important! This API's current version is v1. When using v0, repeating a create schedule request after a schedule is created will update the details of that particular schedule.

Create Schedule Request Attributes

The following JSON sample provides a more readable version of the content contained in the above curl example. This example represents the attributes and values contained in the -d flag of the curl example.

Create Schedule Sample POST Body(JSON) for Create Schedule

{
    "environment_id": "951b681e-0a16-44ab-acfb-505a0a8564e9",
    "interval": "1d",
    "note": "Once a day schedule"
}

Response 201 CREATED

{
    "data": {
            "environment_id": "1eeb3695-5d0f-467c-9d51-8b773dce29ba",
            "interval": "1h",
            "note": "Staging Environment",
            "id": "084e6df7-9165-46d2-9e1c-b87ccfc53d18"
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}

Attributes

• environment_id string

  required

  The id of the environment to use when running the test

• interval string

  required

  The schedule's interval, must be one of:

  • 1m — every minute
  • 5m — every 5 minutes
  • 15m — every 15 minutes
  • 30m — every 30 minutes
  • 1h — every hour
  • 6h — every 6 hours
  • 1d — every day

• note string

  A human-friendly description for the schedule

Modify Schedule

Modify Schedule

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/schedules/<schedule_id>' \
    -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"environment_id": "1eeb3695-5d0f-467c-9d51-8b773dce29ba","interval": "5m","note": "Production Monitoring Schedule"}'

Update the details of a single schedule by making a PUT request with a JSON body to the schedule details resource. Updating a schedule will cause the test to execute starting at the time of the request on the given interval.

Modify Schedule Data Attributes

The following JSON sample provides a more readable version of the content contained in the above curl example. This example represents the attributes and values contained in the -d flag of the curl example.

Modify Schedule Sample PUT Body(JSON) for Modify Schedule

{
    "environment_id": "1eeb3695-5d0f-467c-9d51-8b773dce29ba",
    "interval": "5m",
    "note": "Production Monitoring Schedule"
}

Response 200 OK

{
    "data": {
            "environment_id": "1eeb3695-5d0f-467c-9d51-8b773dce29ba",
            "interval": "1h",
            "note": "Staging Environment",
            "id": "084e6df7-9165-46d2-9e1c-b87ccfc53d18"
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}

Attributes

• environment_id string

  required

  The id of the environment to use when running the test

• interval string

  required

  The schedule's interval, must be one of:

  • 1m — every minute
  • 5m — every 5 minutes
  • 15m — every 15 minutes
  • 30m — every 30 minutes
  • 1h — every hour
  • 6h — every 6 hours
  • 1d — every day

• note string

  A human-friendly description for the schedule

Delete Test Schedule

Delete Test Schedule

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/schedules/<schedule_id>' \
    -X DELETE \
    -H 'Authorization: Bearer <access_token>'

Response 204 NO CONTENT

Delete (or stop) a schedule.

Results

Retrieve details for API Tests and results in a given bucket.

The APIs include the following details:

In the summary section:

• subtests_count: Total number of Subtests
• subtests_passed: Number of Subtests Passed
• subtests_failed: Number of Subtests Failed
• subtests_others: Number of Subtests that failed for other reasons
• agent_expired: If BlazeMeter is unable to communicate with your agent regularly, test results that attempt to use that agent will be marked as agent expired. For more information, see Remote Agent Expired.

For each subtest in a test (subtest details):

• name: Name of the Subtest
• note: Note (description) of the Subtest
• test_uuid: Test ID of the Subtest
• test_run_uuid: Test Run ID of the Subtest
• test_run_url: Test Run URL for the Subtest
• started_at: Start Time of the Subtest
• finished_at: End Time of the Subtest
• result: Result of the Subtest

When using a Test with Subtests as a Test Suite, you can get details about the Parent Test (the Test Suite) and also details about each Subtests (the individual Tests in a Test Suite).

When a Test fails with a Remote Agent Expired error, the result indicates the reason for the failure accordingly.

Test Result List

Test Result List

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/results' \
    -H 'Authorization: Bearer <access_token>'

A list of all results for a given test, including results and those currently in progress.

Test Result List Request Parameters

Response 200 OK

{
    "data": [
        {
            "agent": null,
            "assertions_defined": 2,
            "assertions_failed": 0,
            "assertions_passed": 2,
            "bucket_key": "6knqwmwvqpzr",
            "finished_at": 1406061608.506811,
            "region": "us1",
            "requests_executed": 1,
            "result": "pass",
            "scripts_defined": 2,
            "scripts_failed": 0,
            "scripts_passed": 2,
            "started_at": 1406036406.68105,
            "test_run_id": "0aa48464-f89e-4596-8d60-79bc678d313f",
            "parent_test_uuid": "b4b0595a-9064-4c36-ac5b-efeeb69583a2",
            "test_run_url": "https://api.runscope.com/buckets/6knqwmwvqpzr/tests/db4cc896-2804-4520-ad06-0caf3bf216a8/results/0aa48464-f89e-4596-8d60-79bc678d313f",
            "test_id": "db4cc896-2804-4520-ad06-0caf3bf216a8",
            "variables_defined": 2,
            "variables_failed": 0,
            "variables_passed": 2,
            "environment_id": "abcdc896-2804-4520-ad06-0caf3bf216a8",
            "environment_name": "My Test Environment"
            "run_by": "John Doe"
            "subtests_count": 0,
            "subtests_passed": 0,
            "subtests_failed": 0,
            "subtests_others": 0,
            "agent_expired": false,
            "subtest_detail": {
                "name": null,
                "note": null,
                "result": null,
                "test_uuid": null,
                "test_run_uuid": null,
                "test_run_url": null,
                "started_at": null,
                "finished_at": null
         }
    ],
    "error": null
}

Attributes

• count integer

  Maximum number of test results to return. Defaults to 10 if not specified. Maximum value is 50

• since float

  Exclusive

  Only return test results started after the given Unix timestamp

• before float

  Exclusive

  Only return test results started before the given Unix timestamp

• subtests boolean

  If true, returns the subtest information

Test Result Detail

Test Result Detail

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/results/<test_run_id>' \
    -H 'Authorization: Bearer <access_token>'

Latest Test Result Detail

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/results/latest' \
    -H 'Authorization: Bearer <access_token>'

Retrieve the details of a given test run by ID.

Test Result Detail Response Attributes

Response 200 OK

{
    "meta": {
        "status": "success"
    },
    "data": {
        "requests": [
            {
                "url": null,
                "method": null,
                "uuid": "3efa15de-9282-4f53-9291-2d14eaf50116",
                "result": null,
                "variables": null,
                "assertions": null,
                "scripts": null,
                "assertions_defined": null,
                "assertions_passed": null,
                "assertions_failed": null,
                "variables_defined": null,
                "variables_passed": null,
                "variables_failed": null,
                "scripts_defined": null,
                "scripts_passed": null,
                "scripts_failed": null,
                "timings": null
            },
            {
                "url": "https://deckofcardsapi.com/api/deck/new/shuffle/?deck_count=1",
                "method": "GET",
                "uuid": "eac758ec-8b32-4235-ab70-9120f2176e38",
                "result": "pass",
                "variables": [
                    {
                        "result": "pass",
                        "source": "json",
                        "property": "deck_id",
                        "name": "deck_id",
                        "value": "8i3go9itqhbf",
                        "error": null
                    }
                ],
                "assertions": [
                    {
                        "result": "pass",
                        "source": "status_code",
                        "property": null,
                        "comparison": "equals_number",
                        "target_value": 200,
                        "actual_value": "200",
                        "error": null
                    },
                    {
                        "result": "pass",
                        "source": "response_time_ms",
                        "property": null,
                        "comparison": "less_than",
                        "target_value": "500",
                        "actual_value": "439.0",
                        "error": null
                    },
                    {
                        "result": "pass",
                        "source": "json",
                        "property": "remaining",
                        "comparison": "equals_number",
                        "target_value": "52",
                        "actual_value": "52",
                        "error": null
                    }
                ],
                "scripts": [],
                "assertions_defined": 3,
                "assertions_passed": 3,
                "assertions_failed": 0,
                "variables_defined": 1,
                "variables_passed": 1,
                "variables_failed": 0,
                "scripts_defined": 0,
                "scripts_passed": 0,
                "scripts_failed": 0,
                "timings": {
                    "dns_lookup_ms": 11.345386505126953,
                    "dial_ms": 2.6960372924804688,
                    "send_headers_ms": 10.195255279541016,
                    "send_body_ms": 0.0019073486328125,
                    "wait_for_response_ms": 425.7347583770752,
                    "receive_response_ms": 0.06461143493652344
                }
            },
            {
                "url": "https://deckofcardsapi.com/api/deck/8i3go9itqhbf/draw/?count=2",
                "method": "GET",
                "uuid": "ef556c3d-d9b7-4afc-af83-6bd8e4a43299",
                "result": "pass",
                "variables": [
                    {
                        "result": "pass",
                        "source": "json",
                        "property": "cards[0].code",
                        "name": "first_card_code",
                        "value": "AD",
                        "error": null
                    },
                    {
                        "result": "pass",
                        "source": "json",
                        "property": "cards[1].code",
                        "name": "second_card_code",
                        "value": "JH",
                        "error": null
                    }
                ],
                "assertions": [
                    {
                        "result": "pass",
                        "source": "status_code",
                        "property": null,
                        "comparison": "equals_number",
                        "target_value": 200,
                        "actual_value": "200",
                        "error": null
                    },
                    {
                        "result": "pass",
                        "source": "response_time_ms",
                        "property": null,
                        "comparison": "less_than",
                        "target_value": "500",
                        "actual_value": "238.0",
                        "error": null
                    },
                    {
                        "result": "pass",
                        "source": "json",
                        "property": "remaining",
                        "comparison": "equals_number",
                        "target_value": "50",
                        "actual_value": "50",
                        "error": null
                    }
                ],
                "scripts": [],
                "assertions_defined": 3,
                "assertions_passed": 3,
                "assertions_failed": 0,
                "variables_defined": 2,
                "variables_passed": 2,
                "variables_failed": 0,
                "scripts_defined": 0,
                "scripts_passed": 0,
                "scripts_failed": 0,
                "timings": {
                    "dns_lookup_ms": 6.918907165527344,
                    "dial_ms": 2.307415008544922,
                    "send_headers_ms": 9.010791778564453,
                    "send_body_ms": 0.002384185791015625,
                    "wait_for_response_ms": 225.95882415771484,
                    "receive_response_ms": 0.064849853515625
                }
            },
            {
                "url": "https://deckofcardsapi.com/api/deck/8i3go9itqhbf/pile/discard/add/?cards=AD%2CJH",
                "method": "GET",
                "uuid": "cd3bab6a-2abf-441c-bdf5-1d8fd4d37c0e",
                "result": "pass",
                "variables": [],
                "assertions": [
                    {
                        "result": "pass",
                        "source": "status_code",
                        "property": null,
                        "comparison": "equals_number",
                        "target_value": 200,
                        "actual_value": "200",
                        "error": null
                    },
                    {
                        "result": "pass",
                        "source": "response_time_ms",
                        "property": null,
                        "comparison": "less_than",
                        "target_value": "500",
                        "actual_value": "239.0",
                        "error": null
                    },
                    {
                        "result": "pass",
                        "source": "json",
                        "property": "piles.discard.remaining",
                        "comparison": "equals_number",
                        "target_value": "2",
                        "actual_value": "2",
                        "error": null
                    }
                ],
                "scripts": [],
                "assertions_defined": 3,
                "assertions_passed": 3,
                "assertions_failed": 0,
                "variables_defined": 0,
                "variables_passed": 0,
                "variables_failed": 0,
                "scripts_defined": 0,
                "scripts_passed": 0,
                "scripts_failed": 0,
                "timings": {
                    "dns_lookup_ms": 9.076356887817383,
                    "dial_ms": 2.7964115142822266,
                    "send_headers_ms": 10.895490646362305,
                    "send_body_ms": 0.001430511474609375,
                    "wait_for_response_ms": 224.6863842010498,
                    "receive_response_ms": 0.05817413330078125
                }
            },
            {
                "url": "https://deckofcardsapi.com/api/deck/8i3go9itqhbf/pile/discard/list/",
                "method": "GET",
                "uuid": "786a296f-56f9-414a-b21c-c85dde52f028",
                "result": "pass",
                "variables": [],
                "assertions": [
                    {
                        "result": "pass",
                        "source": "status_code",
                        "property": null,
                        "comparison": "equals_number",
                        "target_value": 200,
                        "actual_value": "200",
                        "error": null
                    },
                    {
                        "result": "pass",
                        "source": "response_time_ms",
                        "property": null,
                        "comparison": "less_than",
                        "target_value": "500",
                        "actual_value": "244.0",
                        "error": null
                    },
                    {
                        "result": "pass",
                        "source": "json",
                        "property": "piles.discard.remaining",
                        "comparison": "equals_number",
                        "target_value": "2",
                        "actual_value": "2",
                        "error": null
                    }
                ],
                "scripts": [],
                "assertions_defined": 3,
                "assertions_passed": 3,
                "assertions_failed": 0,
                "variables_defined": 0,
                "variables_passed": 0,
                "variables_failed": 0,
                "scripts_defined": 0,
                "scripts_passed": 0,
                "scripts_failed": 0,
                "timings": {
                    "dns_lookup_ms": 9.302854537963867,
                    "dial_ms": 3.0939579010009766,
                    "send_headers_ms": 9.891033172607422,
                    "send_body_ms": 0.0016689300537109375,
                    "wait_for_response_ms": 230.18383979797363,
                    "receive_response_ms": 0.06842613220214844
                }
            }
        ],
        "assertions_defined": 12,
        "assertions_passed": 12,
        "assertions_failed": 0,
        "bucket_key": "koa6ctwsgx9k",
        "started_at": 1639677275.7,
        "variables_defined": 3,
        "variables_passed": 3,
        "variables_failed": 0,
        "finished_at": 1639677286.6,
        "requests_executed": 4,
        "agent": null,
        "scripts_defined": 0,
        "scripts_passed": 0,
        "scripts_failed": 0,
        "result": "pass",
        "test_id": "4912dd0e-4522-49fa-9bc1-ffa20821a6d6",
        "test_run_id": "7d0236a0-469d-4b2a-b882-64acd2cb685f",
        "parent_test_uuid": "7abab89c-2a2d-4600-badc-44a75b60e5ad",
        "source": "scheduled",
        "region": "au1",
        "test_run_url": "https://api.runscope.com/buckets/koa6ctwsgx9k/tests/4912dd0e-4522-49fa-9bc1-ffa20821a6d6/results/7d0236a0-469d-4b2a-b882-64acd2cb685f",
        "environment_id": "d925b6b4-3aa3-4220-8a3b-7437f24f647c",
        "environment_name": "Prod Settings",
        "run_by": "Jane Doe",
        "subtests_count": 0,
        "subtests_passed": 0,
        "subtests_failed": 0,
        "subtests_others": 0,
        "agent_expired": false,
        "subtest_detail": {
            "name": null,
            "note": null,
            "result": null,
            "test_uuid": null,
            "test_run_uuid": null,
            "test_run_url": null,
            "started_at": null,
            "finished_at": null
        }
    },
    "error": null
}

Attributes

• agent string

  The ID of the agent used to execute this request. If an API Monitoring location was used, null

• assertions_defined integer

  The total number of simple assertions (non-script) defined for all requests in this test run

• assertions_failed integer

  The total number of simple assertions that failed for all requests in this test run

• assertions_passed integer

  The total number of simple assertions that passed for all requests in this test run

• bucket_key string

  The key for the bucket that contains the test that caused this test run

• finished_at float

  The Unix timestamp representing when the test run completed

• region string

  The region code for the API Monitoring location used to execute the test run. If an agent was used, null

• requests array

  A list of the request details

  Show/Hide Child Attributes

  • uuid string

    The unique ID for the individual test step. Can be used with the Test Step Detail resource to retrieve full HTTP request and response details for request and incoming request steps

  • result string

    The aggregate result of variables, assertions, and scripts processed for this test run. Either pass (all passed) or fail (any failed)

  • url string

    The URL that was used for this request

  • method string

    The HTTP method used for this request

  • assertions_defined integer

    The number of simple assertions (non-script) defined for this request

  • assertions_failed integer

    The number of simple assertions (non-script) that failed for this request

  • assertions_passed integer

    The number of simple assertions (non-script) that passed for this request

  • scripts_defined integer

    The number of scripts defined for this request

  • scripts_failed integer

    The number of scripts that failed for this request

  • scripts_passed integer

    The number of scripts that passed for this request

  • variables_defined integer

    The number of simple variables (non-script) defined for this request

  • variables_failed integer

    The number of simple variables (non-script) that failed for this request

  • variables_passed integer

    The number of simple variables (non-script) that passed for this request

  • assertions array

    List of assertions in this test

    Show/Hide Child Attributes

    • result string

      The pass/fail result for this assertion

    • source string

      The data source for the assertion. Possible values are json, xml, response_headers, response_size_bytes, response_time_ms or status_code

    • property string

      The target property within the data source used to locate the actual value

    • comparison string

      The comparison used to compare the target and expected values. Possible values are equals, does_not_equal, is_empty, is_not_empty, greater_than_or_equal, greater_than, less_than_or_equal, less_than, equals_number, contains, does_not_contain, has_key or has_value

    • target_value string

      The value to compare against

    • actual_value string

      The actual value extracted during the test run

    • error null

      If the assertion failed, a description of the failure. If the assertion passed, null

  • scripts array

    List of scripts for this test

    Show/Hide Child Attributes

    • result string

      The pass/fail result of the script

    • output string

      Any log output from the script execution

    • error null

      Additional information if a script fails

  • timings object

    The timing details for this test

    Show/Hide Child Attributes

    • dns_lookup_ms float

      Total time for DNS lookup in milliseconds

    • dial_ms float

      Total time connecting to server in milliseconds

    • send_headers_ms float

      Total time to send headers in milliseconds

    • send_body_ms float

      Total time to send request body in milliseconds

    • wait_for_response_ms float

      Total time waiting for response in milliseconds

    • receive_response_ms float

      Total time to receive response in milliseconds

  • variables array

    List of variables used in this test

    Show/Hide Child Attributes

    • result string

      The pass/fail result for this variable

    • source string

      The data source for the variable. Possible values are json, xml, response_headers, response_size_bytes, response_time_ms or status_code

    • property string

      This is the property used to extract the value you are looking for. See here for more details

    • name string

      The name of the variable

    • value integer

      The value used for this variable

    • error string

      The error produced by this error

• requests_executed integer

  The number of requests executed in this test run

• result string

  The overall result of the test run. Possible values are: pass, fail, working, canceled, or queued

• scripts_defined integer

  The number of scripts defined across all requests in this test run

• scripts_failed integer

  The number of scripts that didn't complete in this test run

• scripts_passed integer

  The number of scripts that were successfully processed in this test run

• started_at float

  The Unix timestamp representing the time the test run was initiated

• test_run_id string

  The unique ID for this test run

• test_id string

  The unique ID for this test

• parent_test_uuid string

  The unique ID for the parent test

• variables_defined integer

  The number of variables defined across all requests in this test run

• variables_failed integer

  The number of variables that failed across all requests in this test run

• variables_passed integer

  The number of variables that passed across all requests in this test run

• run_by string

  The user performing the test run

• subtests boolean

  If true, returns the subtest information

Test Result Step Detail

Test Result Step Detail

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/results/<test_run_id>/steps/<step_id>' \
    -H 'Authorization: Bearer <access_token>'

Retrieve the HTTP request and response details of a given test step within a test run by ID. Supported step types are request and incoming request (pauses, Ghost Inspector and conditional steps are not supported).

Test Step Result Detail Response Attributes

Response 200 OK

{
    "data": {
        "bucket_key": "vnms9d3tgg4u",
        "uuid": "7a8daf40-60ea-44d8-9b4c-4695b76f3a1d",
        "request": {
            "body": "",
            "body_encoding": "plaintext",
            "headers": {
                "Accept": [
                    "*/*"
                ],
                "Accept-Encoding": [
                    "gzip, deflate, compress"
                ],
                "Host": [
                    "api-twilio-com-vnms9d3tgg4u.runscope.net"
                ],
                "User-Agent": [
                    "runscope/1.0"
                ]
            },
            "host": "api.twilio.com",
            "method": "GET",
            "params": {},
            "path": "/",
            "scheme": "https",
            "timestamp": 1368828807.918586
        },
        "response": {
            "body": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<TwilioResponse><Versions page=\"0\" numpages=\"1\" pagesize=\"50\" total=\"2\" start=\"0\" end=\"1\" uri=\"/\" firstpageuri=\"\" previouspageuri=\"\" nextpageuri=\"\" lastpageuri=\"\"><Version><Name>2008-08-01</Name><Uri>/2008-08-01</Uri><SubresourceUris><Accounts>/2008-08-01/Accounts</Accounts></SubresourceUris></Version><Version><Name>2010-04-01</Name><Uri>/2010-04-01</Uri><SubresourceUris><Accounts>/2010-04-01/Accounts</Accounts></SubresourceUris></Version></Versions></TwilioResponse>\n",
            "body_encoding": "plaintext",
            "headers": {
                "Content-Length": [
                    "511"
                ],
                "Content-Type": [
                    "application/xml"
                ]
            },
            "reason": "OK",
            "size_bytes": 511,
            "status": 200,
            "timestamp": 1368828808.555258
        }
    },
    "meta": {
        "status": "success"
    }
}

Attributes

• bucket_key string

  The bucket where this request step is stored

• uuid string

  The unique identifier (UUID) for this request/response pair

• request object

  The request details for this test result

  Show/Hide Child Attributes

  • body string

    A plain-text or base64-encoded string of data. For binary content (like images), we have base64 encoded the content so it can be returned in a JSON object. The key "body_encoding" will be set accordingly for base64 encoded bodies

  • body_encoding string

    The encoding of the request.body. Either 'plaintext' or 'base64'

  • headers object

    The HTTP request headers as an object. The keys of this object are header names and the value is an array of values

    Show/Hide Child Attributes

    • headerName array

      The header name of this header (i.e. Accept) and it's list of values for this header name (i.e. */*)

  • host string

    The destination hostname of the HTTP request

  • method string

    The HTTP method of the request

  • params object

    Any querystring parameters in the request as an object. The keys of this object are parameter names, and the value is an array of values

  • path string

    The path portion of the HTTP request

  • scheme string

    The scheme of the request. (http or https)

  • timestamp float

    A unix timestamp representing the time the request was made. This is a floating point number that with microsecond granularity

  • body string

    A plain-text or base64-encoded string of data. For binary content (like images), we have base64 encoded the content so it can be returned in a JSON object. The key "body_encoding" will be set accordingly for base64 encoded bodies

  • body_encoding string

    The encoding of the request.body. Either 'plaintext' or 'base64'

• response object

  The response details for this test result

  Show/Hide Child Attributes

  • body string

    A plain-text or base64-encoded string of data. For binary content (like images), we have base64 encoded the content so it can be returned in a JSON object. The key "body_encoding" will be set accordingly for base64 encoded bodies

  • body_encoding string

    The encoding of the response.body. Either 'plaintext' or 'base64'

  • headers object

    The HTTP response headers as an object. The keys of this object are header names and the value is an array of values

    Show/Hide Child Attributes

    • headerName array

      The header name of this header (i.e. Accept) and it's list of values for this header name (i.e. */*)

  • reason string

    Text status reason that corresponds to response.status. e.g. - 'OK', 'Not Found', etc

  • size_bytes integer

    The size of the response body in bytes

  • status integer

    Integer status code for the HTTP response

  • timestamp float

    A unix timestamp representing the time the response was received. This is a floating point number that with microsecond granularity

Metrics

Retrieve the metrics shown on the API Monitoring dashboard of a given test by ID.

Test Metrics

A list of metrics for a given test, including average response time, success ratio, and overall changes in performance compared to the previous time period.

Test Metrics

curl 'https://api.runscope.com/buckets/<bucket_key>/tests/<test_id>/metrics' \
    -H 'Authorization: Bearer <access_token>'

Response 200 OK

{
    "response_times":[
        {
            "success_ratio":0.3333333333333333,
            "timestamp":1494964800,
            "avg_response_time_ms":44
        },
        {
            "success_ratio":1.0,
            "timestamp":1494968400,
            "avg_response_time_ms":35
        },
        {
            "success_ratio":0.4,
            "timestamp":1494972000,
            "avg_response_time_ms":40
        },
        {
            "success_ratio":0.5517241379310345,
            "timestamp":1494975600,
            "avg_response_time_ms":39
        },
        {
            "success_ratio":1.0,
            "timestamp":1494979200,
            "avg_response_time_ms":41
        },
        {
            "success_ratio":0.956081081081081,
            "timestamp":1494982800,
            "avg_response_time_ms":68
        },
        {
            "success_ratio":1.0,
            "timestamp":1494986400,
            "avg_response_time_ms":105
        },
        {
            "success_ratio":1.0,
            "timestamp":1494990000,
            "avg_response_time_ms":38
        },
        {
            "success_ratio":1.0,
            "timestamp":1494993600,
            "avg_response_time_ms":37
        },
        {
            "success_ratio":1.0,
            "timestamp":1494997200,
            "avg_response_time_ms":44
        },
        {
            "success_ratio":1.0,
            "timestamp":1495000800,
            "avg_response_time_ms":36
        },
        {
            "success_ratio":1.0,
            "timestamp":1495004400,
            "avg_response_time_ms":36
        },
        {
            "success_ratio":1.0,
            "timestamp":1495008000,
            "avg_response_time_ms":48
        },
        {
            "success_ratio":0.9965397923875432,
            "timestamp":1495011600,
            "avg_response_time_ms":46
        },
        {
            "success_ratio":1.0,
            "timestamp":1495015200,
            "avg_response_time_ms":45
        },
        {
            "success_ratio":1.0,
            "timestamp":1495018800,
            "avg_response_time_ms":52
        },
        {
            "success_ratio":1.0,
            "timestamp":1495022400,
            "avg_response_time_ms":90
        },
        {
            "success_ratio":1.0,
            "timestamp":1495026000,
            "avg_response_time_ms":83
        },
        {
            "success_ratio":1.0,
            "timestamp":1495029600,
            "avg_response_time_ms":47
        },
        {
            "success_ratio":1.0,
            "timestamp":1495033200,
            "avg_response_time_ms":44
        },
        {
            "success_ratio":1.0,
            "timestamp":1495036800,
            "avg_response_time_ms":43
        },
        {
            "success_ratio":1.0,
            "timestamp":1495040400,
            "avg_response_time_ms":44
        },
        {
            "success_ratio":1.0,
            "timestamp":1495044000,
            "avg_response_time_ms":37
        },
        {
            "success_ratio":0.5714285714285714,
            "timestamp":1495047600,
            "avg_response_time_ms":29
        }
    ],
    "change_from_last_period":{
        "response_time_50th_percentile":0.05284147557328004,
        "response_time_99th_percentile":-0.03965577026132455,
        "total_test_runs":0.0313588850174216,
        "response_time_95th_percentile":0.2567257314416911
    },
    "environment_uuid":"all",
    "region":"all",
    "timeframe":"day",
    "this_time_period":{
        "response_time_50th_percentile":44.0,
        "response_time_99th_percentile":101.54999999999998,
        "total_test_runs":296,
        "response_time_95th_percentile":88.94999999999997
    }
}

This API returns an array of test response times with an interval of minutes/hours/days, depending on the timeframe filter you use when making the request. Each response time object contains the success_ratio (between 0.0, all fails, to 1.0, all passes), timestamp in Unix format, and avg_response_time_ms properties.

The response also includes two objects: this_time_period, which includes the average response time in milliseconds of all the data points that fall within the 50th, 95th, and 99th percentile, and change_from_last_period, which includes the difference in response time for the same percentiles. For example, if you have the property response_time_99th_percentile: 43.91291 in this_time_period, that means that the average response time of 99% of your tests fall at or under 43.9ms, and 1% fall above.

You can use those values to have a better idea if your tests have been getting slower, consistent, or faster, as time progresses.

Test Metrics Request Parameters

Attributes

• region string

  The region code for the test service region you wish to get results from. E.g.: us1 for US Virginia location. Default value is all

• timeframe string

  The timeframe you want to filter your results. Default value is day. Accepted values are hour, day, week, and month

• environment_uuid string

  Filter the metrics results by a given environment ID. Default value is all

Regions

Regions List

curl 'https://api.runscope.com/regions' \
    -H 'Authorization: Bearer <access_token>'

Response 200 OK

{
    "data": {
        "regions": [
            {
                "region_code": "us1",
                "location": "US East (Northern Virginia)",
                "service_provider": "Amazon Web Services",
                "hostname": "us1.runscope.net"
            }
        ]
    },
    "meta": {
        "status": "success"
    }
}

Information about the available service regions that you can use to send requests through Runscope.

Account

Account

curl 'https://api.runscope.com/account'

Information about the authorized account.

Account Response Attributes

Response 200 OK

{
    "data": {
        "name": "Grace Hopper", 
        "uuid": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9", 
        "email": "grace@example.com", 
        "teams": [
            {
                "uuid": "1234abcd-7fe1-43cb-aa12-ef50420f2cf9",
                "name": "Amazing Grace"
            }
        ]
    }, 
    "meta": {
        "status": "success"
    }
}

Attributes

• name string

  The name of the person for this account

• uuid string

  The unique identifier for this account

• email string

  The email address for this account. Only present if authorized with the account:email scope

• teams array

  List of team details for this account

  Show/Hide Child Attributes

  • uuid string

    The unique identifier for this team

  • name string

    The name of this team

Buckets

Retrieve details for the buckets available to the authorized account. If the account belongs to multiple teams, buckets for all the teams the belong to are accessible.

Bucket List

Bucket List

curl 'https://api.runscope.com/buckets' \
    -H 'Authorization: Bearer <access_token>'

Response 200 OK

{
    "data": [
        {
            "auth_token": null,
            "default": false,
            "key": "z20co0kgljjk",
            "name": "Lucky Notebook",
            "team": {
                "name": "Personal Team",
                "uuid": "7a7a0917-91d7-43ef-b8f4-fe31762167e0"
            },
            "verify_ssl": true
        },
        {
            "auth_token": null,
            "default": false,
            "key": "ov2f2tqifoov",
            "auth_token": "7n7n0917-91q7-43rs-o8s4-sr31762167r0",
            "name": "Mobile Apps",
            "team": {
                "name": "Mobile Team",
                "uuid": "7a7a0917-91d7-43ef-b8f4-fe31762167e0"
            },
            "verify_ssl": true
        },
    ],
    "meta": {
        "status": "success"
    }
}

These bucket keys may be used to make requests through BlazeMeter API Monitoring to capture API data on behalf of the authorized account. Authenticated buckets are only returned if you are authorized with the bucket:auth_token scope.

Bucket Detail

Test Result Detail v1

curl 'https://api.runscope.com/v1/buckets/<bucket_key>' \
    -H 'Authorization: Bearer <access_token>'

Test Result Detail v0

curl 'https://api.runscope.com/buckets/<bucket_key>' \
    -H 'Authorization: Bearer <access_token>'

Retrieve the details of a given bucket by key.

Note: The list_utilizations_gt attribute is available with Runscope API v1 or higher. For more information, see the Bucket Utilization API documentation.

Bucket Detail Response Attributes

Response 200 OK

{
    "data": {
        "auth_token": null,
        "default": false,
        "key": "ov2f2tq1floq",
        "name": "Mobile Apps",
        "team": {
            "name": "Mobile Team",
            "uuid": "7a7a0917-91d7-43ef-b8f4-fe31762167e0"
        },
        "verify_ssl": true,
        "locations_utilization_%": {
            "remote": 82,
            "US California": 86, 
            "US Iowa": 90
        }
    },
    "meta": {
        "status": "success"
    }
}

Attributes

• auth_token string

  Bucket auth token if set, otherwise this value is null

• default boolean

  True if this bucket is the 'default' for a team. Default buckets cannot be deleted

• key string

  The unique identitifer used to address a bucket

• name string

  The name of this bucket as displayed in your dashboard

• team object

  An object describing the team this bucket belongs to. Includes the name and uuid of the team

  Show/Hide Child Attributes

  • name string

    The name of this team

  • uuid string

    The unique identifier for this team

• verify_ssl boolean

  True if this bucket is configured to verify ssl for requests made to it

• list_utilizations_gt integer

  List the percentage of concurrent tests running in each location that meets or exceeds a certain threshold. If unspecified, the default threshold is 85%.

Bucket Custom Emails

Bucket Custom Emails List

curl 'https://api.runscope.com/buckets/<bucket_key>/custom-emails' \
    -H 'Authorization: Bearer <access_token>'

You can configure email notifications so that test results are sent to custom email addresses (non-member emails, external emails, or distribution list emails).

Important! In order to add a custom email address, you first need to whitelist its email domain. See Team Email Domains for details.

Response 200 OK

{
    "meta": {
        "status": "success"
    },
    "data": [
        {
            "uuid": "a250d664-10bb-4520-98f1-ae706e37050a",
            "custom_email": "abcd@gmail.com",
            "description": "custom email 1",
            "bucket_key": "q4nomk5x1yk7",
            "team_uuid": "576cdce0-c0f6-4d0e-bf49-6ff75604b783",
            "created_by": "92f70ebd-d8cc-47d8-bddb-0f1da1e6c8ca",
            "created_at": 1617176809
        },
        {
            "uuid": "c6aefe9b-eb98-4438-b7f3-cdfa8128d289",
            "custom_email": "efgh@yahoo.com",
            "description": "custom email 2",
            "bucket_key": "q4nomk5x1yk7",
            "team_uuid": "576cdce0-c0f6-4d0e-bf49-6ff75604b783",
            "created_by": "92f70ebd-d8cc-47d8-bddb-0f1da1e6c8ca",
            "created_at": 1617176809
        },
        {
            "uuid": "f7de248a-4f3f-4412-8514-26b80512d7f3",
            "custom_email": "wxyz@gmail.com",
            "description": "custom email 3",
            "bucket_key": "q4nomk5x1yk7",
            "team_uuid": "576cdce0-c0f6-4d0e-bf49-6ff75604b783",
            "created_by": "92f70ebd-d8cc-47d8-bddb-0f1da1e6c8ca",
            "created_at": 1617176809
        }
    ],
    "error": null
}

Add Custom Email to Bucket

Add Custom Email to Bucket

curl 'https://api.runscope.com/buckets/<bucket_key>/custom-emails' \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"team_uuid": "Mandatory Team UUID argument","email": "Mandatory Email ID argument","description": "Optional description argument","created_by": "Optional user UUID"}'

Response 200 OK

{
"error": null,
"meta": {
"status": "success"
}
}

Delete Custom Email from Bucket

Delete Custom Email from Bucket

curl 'https://api.runscope.com/buckets/<bucket_key>/custom-emails' \
    -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"email": "Mandatory Email ID argument"}'

Response 204 NO CONTENT

{
"error": "Email user01@gmail.com is not part of the bucket q4nomk5x1yk7",
"meta": {
"status": "error"
}
}

Creating a Bucket

Creating a Bucket

curl 'https://api.runscope.com/buckets?name=Mobile%20Team&team_uuid=7a7a0917-91d7-43ef-b8f4-fe31762167e0' \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>'

Create a new test environment by POSTing a JSON body with the environment details.

Creating a Bucket Request Parameters

Parameters

• name string

  required

  Name of this bucket

• uuiteam_uuidd string

  required

  Unique identifier for the team this to create this bucket for

Creating a Bucket Response Attributes

Response 201 CREATED

{
    "data": {
        "auth_token": null,
        "default": false,
        "key": "ov2f2tq1floq",
        "name": "Mobile Apps",
        "team": {
            "name": "Mobile Team",
            "uuid": "7a7a0917-91d7-43ef-b8f4-fe31762167e0"
        },
        "verify_ssl": true
    },
    "meta": {
        "status": "success"
    }
}

Attributes

• auth_token string

  Bucket auth token if set, otherwise this value is null

• default boolean

  True if this bucket is the 'default' for a team. Default buckets cannot be deleted

• key string

  The unique identitifer used to address a bucket

• name string

• team object

  An object describing the team this bucket belongs to. Includes the name and uuid of the team

  Show/Hide Child Attributes

  • name string

    The name of this team

  • uuid string

    The unique identifier for this team

• verify_ssl boolean

  True if this bucket is configured to verify ssl for requests made to it

Deleting a Bucket

Deleting a Bucket

curl 'https://api.runscope.com/buckets/<bucket_key>' \
    -X DELETE \
    -H 'Authorization: Bearer <access_token>'

Response 204 NO CONTENT

Delete a bucket by key. Note: You cannot delete the default bucket on an account.

Teams

The /teams endpoints allow you to:

• List team members,
• Look up user details,
• Look up all groups within a team,
• Look up group memberships,
• Invite and remove users from teams, and
• Manage whitelisted email domains associated with a given team.

Team Members List

Team Members List

curl 'https://api.runscope.com/teams/<team_id>/people' \
    -H 'Authorization: Bearer <access_token>'

Teams Response Attributes

Response 200 OK

[
    {
        "name": "Grace Hopper",
        "created_at": "Wed, 14 Aug 2019 19:53:48 -0000",
        "id": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9",
        "last_login_at": "Thu, 21 Nov 2019 15:22:00 -0000",
        "role_name": "User Group",
        "email": "grace@example.com",
        "uuid": "4ee15ecc-7fe1-43cb-aa12-ef50420f2cf9",
    },
    {
        "name": "Ada Lovelace",
        "created_at": "Sun, 14 Apr 2019 13:07:23 -0000",
        "id": "84fa0764-ba80-4f0e-8e33-1ad12280f3f1",
        "last_login_at": "Tue, 04 Feb 2020 09:47:32 -0000",
        "role_name": "User Group",
        "email": "ada@example.com",
        "uuid": "84fa0764-ba80-4f0e-8e33-1ad12280f3f1"
    },
]

Attributes

• name string

  The name of the person

• uuid string

  The unique identifier for this person's account

• email string

  The email address for this account. Only present if authorized with the account:email scope

• page integer

  Return the desired page of results.

• count integer

  Specifies the maximum number of results to return. Maximum value is 200.

  Note: If the count is more than 200, use the page attribute in the call. As an example, to return the entire team list of a 359-member team you would need to call:

  ?count=200&page=1
?count=200&page=2

  The end-user should call this API in a loop with a constant count value while incrementing page in each pass through the loop until the data[] array returned by the API is zero-length.

Look Up User

Look Up User Details

curl 'https://api.runscope.com/teams/<team_id>/people/<email>' \
    -H 'Authorization: Bearer <access_token>'

Returns user details associated with an email.

Response 200 OK

{
    "meta": {
        "status": "success"
    },
    "data": {
        "id": "d24561e8-5331-4168-933e-bc24a0d9e30a",
        "uuid": "d24561e8-5331-4168-933e-bc24a0d9e30a",
        "name": "User9090",
        "email": "user9090@perforce.com",
        "created_at": 1660800577,
        "role_name": "Administrator"
    },
    "error": null
}

Look Up Groups in Team

Look Up Groups in Team

curl 'https://api.runscope.com/teams/<team_id>/groups' \
    -H 'Authorization: Bearer <access_token>'

Return the list of groups within a team.

Response 200 OK

{
    "error": null,
    "meta": {
        "status": "success"
    },
    "data": [
        {
            "name": "Group1",
            "uuid": "6ee0c1d0-ca65-4eaa-92d2-aa6e0a0324a0"
        },
        {
            "name": "Group2",
            "uuid": "469301f2-c525-45d2-8e89-09ddeb46853e"
        }
    ]
}

Look Up Group Membership

Look Up User's Group Membership

curl 'https://api.runscope.com/teams/<team_id>/people/<email>/groups ' \
    -H 'Authorization: Bearer <access_token>'

Returns a user's membership in groups within the specified team, using their email and team_id.

Response 200 OK

{
    "meta": {
        "status": "success"
    },
    "data": [{
        "uuid": "651afb6c-af35-4c2c-9e19-ec0637e44e3f",
        "name": "Group1"
        "team_uuid": "c3bdc553-d214-405f-bc30-78561a8c0aeb",
    }]
    "error": null
}

Invite User

Invite Users to Team

curl 'https://api.runscope.com/teams/<team_id>/invite' \
    -X POST \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"emails": ["grace.hopper@gmail.com", "jane.doe@gmail.com"], "role_uuid":"e90f9a7d-9611-46a8-bb4d-80d77e6be1f1",
  "group_uuids": ["d9d4ba85-8d41-4e71-905e-d6a68ff08801","d35499f7-db48-4ebc-ab04-0ae2019bfba5"]}'

Invite users to the team and assign role and group(s) to them.

Response 201 OK

{
    "error": null,
    "meta": {
        "status": "success"
    },
    "data": {
        "successes": [
            "grace.hopper@gmail.com",
            "jane.doe@gmail.com"
        ],
        "errors": []
    }
}

Attributes

• emails string

  required

  Email addresses of users to invite, separated by comma

• role_uuid string

  [Optional] The role to put the users in. See Role Based Access Control

• group_uuids string

  [Optional] The group(s) to include the users in

Remove User

Remove User from Team

curl 'https://api.runscope.com/teams/<team_id>/people/<email>' \
    -X DELETE \
    -H 'Authorization: Bearer <access_token>'

Remove a user from a team.

Limitations

The API call will not remove user/users under the following conditions:

• If the user is an owner of the team
• If there is only one user in the team

Response 204 DELETED

Team Email Domains

Team Email Domains List

curl 'https://api.runscope.com/teams/<team_id>/email-domains' \
    -H 'Authorization: Bearer <access_token>'

You can view and add custom email domains to email notification domain whitelist.

Response 200 OK

{
    "meta": {
        "status": "success"
    },
    "data": {
        "team_uuid": "e54c1b37-895f-434c-86f3-4606a49242af",
        "email_whitelist_domains": "gmail.com,yahoo.com,perforce.com",
        "updated_by": "92f70ebd-d8cc-47d8-bddb-0f1da1e6c8ca",
        "updated_at": 1617129570
    },
    "error": null
}

Update Whitelist Domains

Insert or Update Whitelist Domains

curl 'https://api.runscope.com/team/<team_id>/email-domains' \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"domainNames": "domain name(s) (separated by comma) argument"}'

Insert or update whitelisted domains.

Response 200 OK

{
    "error": null,
    "meta": {
        "status": "success"
    }
}

Integrations

List 3rd-party connected services associated with a given team.

Team Integrations List

Team Integrations List

curl 'https://api.runscope.com/teams/<team_id>/integrations' \
    -H 'Authorization: Bearer <access_token>'

Response 200 OK

[
    {
        "description": "PagerDuty: Production Alerts",
        "type": "pagerduty",
        "uuid": "cf95026e-8951-4ae1-83a7-699243678490"
    },
    {
        "description": "Slack: #api-tests channel, send message on failed test runs",
        "type": "slack",
        "uuid": "12014ba3-f5d7-448f-8740-f5ca2f498674"
    }
]

Integrations Response Attributes

Attributes

• uuid string

  The unique identifier for this integrated service instance

• description string

  The human-friendly description of the integrated service instance

• type string

  The external service type for this integrated service instance

Agents

List currently connected agents associated with a given team.

Team Agents List

Team Agents List

curl 'https://api.runscope.com/v1/teams/<team_id>/agents'

Agents Response Attributes

Response 200 OK

{
    "meta": {
        "status": "success"
    },
    "data": [
        {
            "version": "go-radar-agent v0.27",
            "agent_id": "79f50f9a-dc4b-403b-8006-fb198356eb95",
            "name": "Grace-Hopper-Macbook.local",
            "team_id": "3343w43-9343434",
            "install_dir": "/opt/bzm/agent",
            "hostname": "server A",
            "ip_address": 127.0.0.1,
            "host_os": "CentOS 8"
        }
    ],
    "error": null
}

Attributes

• version string

  The version for this agent

• agent_id string

  The unique identifier for this agent

• name string

  The name of the agent set in the configuration file or with the command line flag

• team_id string

  The ID of the team involved

• install_dir string

  Directory location where the agent is installed

• hostname string

  Name of the host where agent is running

• ip_address string

  IP address assigned to the host where agent is running

• host_os string

  Operating System type of the host where the agent is running

Role Based Access Control

Assign, modify, or un-assign a built-in or custom role to/from a user or team group.

Available Permissions

Permissions

• team:billing:view array

  View billing information for a team

• team:billing:modify string

  Change billing information for a team

• team:people:view integer

  View all members of a team

• team:people:modify array

  Add or delete team members

• team:people:invite string

  Invite members to a team

• team:buckets:modify string

  Change settings in buckets, delete buckets, change bucket names

• team:buckets:add string

  Add new buckets

• team:gateway_agent:allow string

  Authorize to sign in via the Gateway Agent

• team:radar_agent:allow string

  Authorize to sign in via the Radar Agent

• team:connected_services:modify string

  Add a connected service

• team:connected_services:delete string

  Delete a connected service

• team:name:modify string

  Change team name

• team:usage:view string

  View team usage

• bucket:tests:view string

  View all tests within a bucket

• bucket:tests:execute string

  Run or cancel tests within a bucket

• bucket:tests:modify string

  Create and edit tests within a bucket

• bucket:tests:delete string

  Delete tests within a bucket

• bucket:tests:share string

  Share the results of a test

• bucket:tests:schedule string

  Add, modify, and delete test schedules within a bucket

• bucket:tests:export string

  Download test exports within a bucket

• bucket:shared_environment:modify string

  Add, modify, and delete shared environments within a bucket

• team:groups:view string

  View group permissions and membership

• team:groups:modify string

  Modify group permissions and membership

• team:script_library:delete string

  Delete script libraries

• team:script_library:modify string

  Modify script libraries

• team:secrets:view string

  View the list of all sensitive variables

• team:secrets:modify string

  Create, edit, and delete sensitive variables

• team:file_upload:modify string

  Upload and delete files

Note: Users with “Manage Private Buckets” permission can access all the private buckets of the organization without creating a Group.

List Roles

Test Environment List

curl 'https://api.runscope.com/teams/<team_id>/roles' \
    -H 'Authorization: Bearer <access_token>'

Response 200 OK

{
    "name": "Read-only Members",
    "permissions": [
        "team:people:view",
        "bucket:alerts:view",
        "bucket:tests:view",
        "bucket:traffic:view",
        "team:secrets:view"
    ],
    "uuid": "6c591177-a19d-41d8-a74e-05ad350c472f"
}

Get the list of the roles in a team.

Returns the details of the roles in a given team.

Create Role

Create Role

curl 'https://api.runscope.com/teams/<team_id>/roles' \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"name": "Viewer","permissions": ["team:people:view"]}'

The following JSON sample provides a more readable version of the content contained in the above curl example. This example represents the attributes and values contained in the -d flag of the curl example.

Create Role Sample POST Body(JSON) for Create Role

{
    "name": "Viewer",
    "permissions": [
        "team:people:view"
    ]
}

Response 201 CREATED

{
    "data": {
        "name": "Viewer",
        "permissions": [
            "team:people:view"
        ],
        "uuid": "f8ad39e1-053b-4bce-b0f1-1564df7b5c9f"
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}

Create a new role by POSTing a JSON body with the role details.

Returns the details of the new role.

Create Role Request Attributes

Attributes

• name string

  Name of this role

• permissions array

  A list of roles to add to this role

Role Details

Role Details

curl 'https://api.runscope.com/teams/<team_uuid>/roles/<role_id>' \
    -H 'Authorization: Bearer <access_token>'

Retrieve the details of a given role by ID.

Returns a single role resource.

Role Details Response Attributes

Response 200 OK

{
    "data": {
        "name": "Viewer",
        "permissions": [
            "team:people:view"
        ],
        "uuid": "f8ad39e1-053b-4bce-b0f1-1564df7b5c9f"
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}

Attributes

• name string

  The name of this role

• permissions array

  A list of the allowed permissions for this role

• uuid string

  The id of this role

Modify Role

Modify Role

curl 'https://api.runscope.com/teams/<team_id>/roles/<role_id>' \
    -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"permissions":["team:people:view","team:usage:view","bucket:tests:view","team:secrets:view"]}'

The following JSON sample provides a more readable version of the content contained in the above curl example. This example represents the attributes and values contained in the -d flag of the curl example. See the example POST body for creating a role.

Modify Role Sample PUT Body(JSON) for Modify Role

{
    "permissions": [
        "team:people:view",
        "team:usage:view",
        "bucket:tests:view",
        "team:secrets:view"
    ]
}

Response 200 OK

{
    "data": {
        "name": "Viewer",
        "permissions": [
            "team:people:view",
            "team:usage:view",
            "bucket:tests:view",
            "team:secrets:view"
        ],
        "uuid": "f8ad39e1-053b-4bce-b0f1-1564df7b5c9f"
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}

Update the permissions of a role by making a PUT request with a JSON body of the environment details.

Returns the updated details of the role.

Delete a Role

Delete Role

curl 'https://api.runscope.com/teams/<team_id>/roles/<role_id>' \
    -X DELETE \
    -H 'Authorization: Bearer <access_token>'

Response 204 NO CONTENT

Delete a role.

Returns a 204 if the role is successfully deleted.

Assign Role

Assign Role

curl 'https://api.runscope.com/teams/<team_id>/people' \
    -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"role_uuid":"5d5435cf-5f9f-47a8-bbd3-2de7bc213758","user_uuids":["9512d659-32c3-4c21-9128-55168fa4e306","a3f5fdc2-049a-451a-8934-b20fd82733af"]}'

The following JSON sample provides a more readable version of the content contained in the above curl example. This example represents the attributes and values contained in the -d flag of the curl example. See the example POST body for creating a role.

Assign Role Sample PUT Body(JSON) for Assign Role

{
    "role_uuid": "5d5435cf-5f9f-47a8-bbd3-2de7bc213758",
    "user_uuids": [
        "9512d659-32c3-4c21-9128-55168fa4e306",
        "a3f5fdc2-049a-451a-8934-b20fd82733af"
    ]
}

Response 200 OK

Assign a role to a list of team members (by ID) by making a PUT request with a JSON body of the environment details.

Returns a 200 in case of success.

Create a Group

Create a Group

curl 'https://api.runscope.com/teams/<team_id>/groups' \
    -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"name": "My New Team Group"}'

Create a new group by POSTing a JSON body with the role details.

Returns the details of the new group.

Create Group Request Attributes

The following JSON sample provides a more readable version of the content contained in the above curl example. This example represents the attributes and values contained in the -d flag of the curl example.

Create a Group Sample POST Body(JSON) for Create a Group

{
    "name": "My New Team Group"
}

Response 201 CREATED

{
    "data": {
        "bucket_keys": null,
        "name": "My New Team Group",
        "user_count": 0,
        "users": null,
        "uuid": "5011528b-4a90-47ba-ab13-9437c8f828b8"
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}

Attributes

• name string

  Name of this group

Group Details

Group Details

curl 'https://api.runscope.com/teams/<team_id>/groups/<group_id>' \
    -H 'Authorization: Bearer <access_token>'

Retrieve the details of a given group by ID.

Returns a single group resource.

Group Details Response Attributes

Response 200 OK

{
    "data": {
        "bucket_keys": [
            "clnhxhzt78zv"
        ],
        "name": "My New Team Group",
        "user_count": 1,
        "users": [
            {
                "email": "hyunji@runscope.com",
                "name": "Hyunji Kim",
                "uuid": "c146cfcc-686a-42b6-97e9-3d4f3c3a3493"
            }
        ],
        "uuid": "5011528b-4a90-47ba-ab13-9437c8f828b8"
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}

Attributes

• bucket_keys array

  The list of bucket IDs attached to this group

• name string

  The name of this group

• user_count integer

  A count of the number of users tied to this group

• users array

  A list of user details tied to this group

• uuid string

  The id of this group

Modify Group

Modify Group

curl 'https://api.runscope.com/teams/<team_id>/groups/<group_id>' \
    -X PUT \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <access_token>' \
    -d '{"bucket_keys":["rtedbn4shvno","clnhxhzt78zv"],"user_uuids":["9512d659-32c3-4c21-9128-55168fa4e306","a3f5fdc2-049a-451a-8934-b20fd82733af"]}'

The following JSON sample provides a more readable version of the content contained in the above curl example. This example represents the attributes and values contained in the -d flag of the curl example.

Modify Group Sample PUT Body (JSON) for Modify Group

{
    "bucket_keys": [
        "rtedbn4shvno",
        "clnhxhzt78zv"
    ],
    "user_uuids": [
        "9512d659-32c3-4c21-9128-55168fa4e306",
        "a3f5fdc2-049a-451a-8934-b20fd82733af"
    ]
}

Response 200 OK

{
    "data": {
        "bucket_keys": [
            "clnhxhzt78zv"
        ],
        "name": "My New Team Group",
        "user_count": 1,
        "users": [
            {
                "email": "hyunji@runscope.com",
                "name": "Hyunji Kim",
                "uuid": "c146cfcc-686a-42b6-97e9-3d4f3c3a3493"
            }
        ],
        "uuid": "5011528b-4a90-47ba-ab13-9437c8f828b8"
    },
    "error": null,
    "meta": {
        "status": "success"
    }
}

Update the bucket keys and/or users in a team group by making a PUT request with a JSON body of the group details.

Returns the updated details of the group.

Delete a Group

Delete Group

curl 'https://api.runscope.com/teams/<team_id>/groups/<group_id>' \
    -X DELETE \
    -H 'Authorization: Bearer <access_token>'

Response 204 NO CONTENT

Delete a group.

Returns a 204 if the group is successfully deleted.

Usage

Get the usage for a specific bucket or team.

Bucket Request Count

Bucket Request Count

curl 'https://api.runscope.com/buckets/<bucket_key>/requests' \
    -H 'Authorization: Bearer <access_token>'

This endpoint will fetch the request usage metrics that were executed by all the tests of the given bucket by key for the last day, by default.

Bucket Request Count Query Parameters

Parameters

• date string

  The timestamp (in YYYY-MM-DD format) that you want a count from (from given date to the the current date)

• days integer

  Number of days to go back and count requests (i.e. 10 would equate to the number of requests made in the last 10 days)

• from string

  Must be used in tandem with to parameter. The timestamp (in YYYY-MM-DD format) that you want a count from

• to string

  Must be used in tandem with from parameter. The timestamp (in YYYY-MM-DD format) that you want a count to

Bucket Request Count Response Attributes

Response 200 OK

{
    "meta": {
        "status": "success"
    },
    "data": {
        "requests_count": 3063237,
        "bucket_key": "61ti2ptvktsg",
        "from_date": "2019-11-14",
        "to_date": "2019-11-15"
    },
    "error": null
}

Attributes

• requests_count integer

  The count of requests made in the specified bucket

• bucket_key string

  The bucket key you specified

• from_date string

  The from date used to for the request count

• to_date string

  The to date used to for the request count

Team Request Count

Team Request Count

curl 'https://api.runscope.com/team/<team_id>/requests' \
    -H 'Authorization: Bearer <access_token>'

This endpoint will fetch the request usage metrics that were executed by all the tests of the given team for the last day, by default.

Team Request Count Query Parameters

Parameters

• date string

  The timestamp (in YYYY-MM-DD format) that you want a count from (from given date to the the current date)

• days integer

  Number of days to go back and count requests (i.e. 10 would equate to the number of requests made in the last 10 days)

• from string

  Must be used in tandem with to parameter. The timestamp (in YYYY-MM-DD format) that you want a count from

• to string

  Must be used in tandem with from parameter. The timestamp (in YYYY-MM-DD format) that you want a count to

Team Request Count Response Attributes

Response 200 OK

{
  "meta": {
    "status": "success"
  },
  "data": {
    "team_uuid": "3c7112ad-ff92-4d54-83c5-2d088706116e",
    "requests_count": 1817949,
    "from_date": "2019-11-14",
    "to_date": "2019-11-15",
    "creator_name": "Sam Aybar",
    "creator_email": "sam@runscope.com",
    "creator_id": "5d859a7d-8a97-4c8a-b4b8-b2125ea0fb00",
    "buckets": [
      {
        "requests_count": 1622360,
        "bucket_key": "61ti2ptvktsg",
        "from_date": "2019-11-14",
        "to_date": "2019-11-15"
      },
      {
        "requests_count": 181307,
        "bucket_key": "bobnzrp9z8ub",
        "from_date": "2019-11-14",
        "to_date": "2019-11-15"
      },
      {
        "requests_count": 12796,
        "bucket_key": "zqcah3ebn1ku",
        "from_date": "2019-11-14",
        "to_date": "2019-11-15"
      },
      {
        "requests_count": 928,
        "bucket_key": "h0op5nyvkt91",
        "from_date": "2019-11-14",
        "to_date": "2019-11-15"
      },
      {
        "requests_count": 547,
        "bucket_key": "b0vjn2xjjkol",
        "from_date": "2019-11-14",
        "to_date": "2019-11-15"
      },
      {
        "requests_count": 10,
        "bucket_key": "iqt75w0wd989",
        "from_date": "2019-11-14",
        "to_date": "2019-11-15"
      },
      {
        "requests_count": 1,
        "bucket_key": "x28c0km6c21g",
        "from_date": "2019-11-14",
        "to_date": "2019-11-15"
      },
      {
        "requests_count": 0,
        "bucket_key": "ljwc8zc1aeda",
        "from_date": "2019-11-14",
        "to_date": "2019-11-15"
      }
    ]
  },
  "error": null
}

Attributes

• team_uuid string

  The team ID that you are gave

• requests_count integer

  The count of requests made in the specified team

• from_date string

  The from date used to for the request count

• to_date string

  The to date used to for the request count

• creator_name string

  The name of the creator of the team

• creator_email string

  The email of the creator of the team

• creator_id string

  The user ID of the creator of the team

• buckets array

  List of buckets tied to this team

  Show/Hide Child Attributes

  • requests_count integer

    The count of requests made in the specified bucket

  • bucket_key string

    The bucket key you specified

  • from_date string

    The from date used to for the request count

  • to_date string

    The to date used to for the request count