Platform API Reference

Welcome to the Load Impact Platform API reference documentation. This documentation should be of interest to anyone who wishes to use or build upon the Load Impact performance testing platform. The API gives you programmatic access to the same set of features used to power the service at loadimpact.com.

Looking for Load Script API docs? It's located on the main site at Load Script API.

General notes


API token

The use the API you need to pass an API token with every request. The API token is to be found on your account page.

Authentication

Authentication is based on HTTP Basic Authentication. Your API token is acts as the username, the password is the empty string. Using cURL this looks like:

curl -u "YOUR_API_TOKEN:"

Version numbers

The current version of the API is 2.

TLS/SSL only

All API requests must be done over encrypted TLS/SSL connections.

Character encoding

Unless otherwise stated every string passed to and from the API needs to be UTF-8 encoded.

Date format

All dates in the API are strings using the ISO 8601 format:

"2013-01-28T12:34:56+00:00"

Error handling


Errors are indicated using standard HTTP response status codes. Accompanying every error is a response body, JSON formatted, with a "message" field describing the error in textual form. The HTTP response status codes of common errors are listed below. More specific errors are detailed in the documentation for the respective API operations.

HTTP status code Description
400 Request was badly formatted
401 Raised if user supplies invalid API key
403 Not allowed to access requested resource
404 Requested resource does not exist
409 Request could not be processed because of a conflict, see documentation for specific resources below for details
422 Request was well formatted but contained semantic errors, see documentation for specific resources below for details
427 Request was rate limited, see Rate limiting below
500 Internal server error occurred while serving request

Rate limiting


The default rate limiting is set to 100 requests per minute. If you need higher limits please contact support.

Data stores


Operations for managing a user's data stores

GET /data-stores

Description

Retrieve data stores associated with a user's account

URL structure
https://api.loadimpact.com/v2/data-stores
API Versions

2

Method

GET

Request

Sample request

curl -X GET "https://api.loadimpact.com/v2/data-stores" \
 -u "API_TOKEN:" 
Response

Sample response

[
    {
        "created": "2016-11-30T11:19:33+00:00", 
        "id": 82070, 
        "name": "Name of resource", 
        "rows": 0, 
        "status": 0, 
        "updated": "2016-11-30T11:19:33+00:00"
    }
]

POST /data-stores

Description

Upload a CSV file to be used as a data store

URL structure
https://api.loadimpact.com/v2/data-stores
API Versions

2

Method

POST

Request

Body (multipart/form-data)

  • String name required Data store name
  • Int fromline required Start using data from specified line number
  • String separator required Character used as separator between CSV fields
  • String delimiter required Character used for quoting
  • File file required CSV file to upload

Sample request

curl -X POST https://api.loadimpact.com/v2/data-stores \
    -u "API_TOKEN:" \
    -H "Accept: application/json" \
    -H "Content-Type: multipart/form-data" \
    -F "file=@data_store.csv" \
    -F "name=My Data Store" \
    -F "fromline=1" \
    -F "separator=comma" \
    -F "delimiter=double"
Response
202

Sample response

{
    "created": "2016-11-30T11:19:33+00:00", 
    "id": 99659, 
    "name": "Name of resource", 
    "rows": 0, 
    "status": 0, 
    "updated": "2016-11-30T11:19:33+00:00"
}
Errors
  • 409 Duplicate, you already have a data store with specified name
Notes

  • This POST request differs from other POST requests in that it sends its payload using the "multipart/form-data" content-type as opposed to the "application/json" content-type. The reason for this is that it involved a file upload.
  • There is a 50 MiB limit to the size of the CSV file to be uploaded.
  • When the CSV file has been uploaded it will be queued for conversion into a representation used by the load generator application.
  • from_line is the 1-based offset of where to start reading in the CSV file
  • Valid values for the separator field are: "comma", "semicolon", "space", and "tab"
  • Valid values for the delimeter field are: "double", "single", and "none"

GET /data-stores/{id}

Description

Retrieve specified data store

URL structure
https://api.loadimpact.com/v2/data-stores/{id}
API Versions

2

Method

GET

Request

Sample request

curl -X GET "https://api.loadimpact.com/v2/data-stores/{id}" \
 -u "API_TOKEN:" 
Response
200

Sample response

{
    "created": "2016-11-30T11:19:33+00:00", 
    "id": 92163, 
    "name": "Name of resource", 
    "rows": 0, 
    "status": 0, 
    "updated": "2016-11-30T11:19:33+00:00"
}
Notes

The status field can be one of the following values:

Status Description
0 Queued
1 Converting
2 Ready
3 Failed

DELETE /data-stores/{id}

Description

Delete specified data store

URL structure
https://api.loadimpact.com/v2/data-stores/{id}
API Versions

2

Method

DELETE

Request

Sample request

curl -X DELETE "https://api.loadimpact.com/v2/data-stores/{id}" \
 -u "API_TOKEN:" 
Response
204
Errors
  • 409 Data store can't be deleted until conversion is complete

Load zones


Operations for retrieving information about load zones

GET /load-zones/{id}

Description

Retrieve all or a specified load zone

URL structure
https://api.loadimpact.com/v2/load-zones/{id}
API Versions

2

Method

GET

Request

Sample request

curl -X GET "https://api.loadimpact.com/v2/load-zones/{id}" \
 -u "API_TOKEN:" 
Response
200

Sample response

[
    {
        "city": "Ashburn", 
        "country": "US", 
        "id": "amazon:us:ashburn", 
        "name": "Name of resource", 
        "vendor": "Amazon"
    }
]

Tests


Operations for managing a user's tests

GET /tests

Description

Retrieve test results associated with a user's account

URL structure
https://api.loadimpact.com/v2/tests
API Versions

2

Method

GET

Request

Sample request

curl -X GET "https://api.loadimpact.com/v2/tests" \
 -u "API_TOKEN:" 
Response
200

Sample response

[
    {
        "ended": "2016-11-30T11:19:33+00:00", 
        "id": 90587, 
        "public_url": "http://loadimpact.com/load-test/example.com-123456abcdef", 
        "started": "2016-11-30T11:19:33+00:00", 
        "status": -1, 
        "status_text": "Created", 
        "title": "I'm a string", 
        "url": "http://www.example.com/"
    }
]
Notes

The status field can be one of the following values:

StatusDescription
-1Created
0Queued
1Initializing
2Running
3Finished
4Timed out (currently not used)
5Aborting by user
6Aborted by user
7Aborting by system
8Aborted by system
9Aborted by script error
10Aborting by threshold
11Aborted by threshold
12Failed threshold

GET /tests/{id}

Description

Retrieve specified test

URL structure
https://api.loadimpact.com/v2/tests/{id}
API Versions

2

Method

GET

Request

Sample request

curl -X GET "https://api.loadimpact.com/v2/tests/{id}" \
 -u "API_TOKEN:" 
Response
200

Sample response

{
    "ended": "2016-11-30T11:19:33+00:00", 
    "id": 69859, 
    "public_url": "http://loadimpact.com/load-test/example.com-123456abcdef", 
    "started": "2016-11-30T11:19:33+00:00", 
    "status": -1, 
    "status_text": "Created", 
    "title": "I'm a string", 
    "url": "http://www.example.com/"
}
Notes

The status field can be one of the following values:

StatusDescription
-1Created
0Queued
1Initializing
2Running
3Finished
4Timed out (currently not used)
5Aborting by user
6Aborted by user
7Aborting by system
8Aborted by system
9Aborted by script error
10Aborting by threshold
11Aborted by threshold
12Failed threshold

POST /tests/{id}/abort

Description

Abort specified test

URL structure
https://api.loadimpact.com/v2/tests/{id}/abort
API Versions

2

Method

POST

Request

Sample request

curl -X POST "https://api.loadimpact.com/v2/tests/{id}/abort" \
 -u "API_TOKEN:" 
Response
204
Errors
  • 409 Test is in a state where it can't be aborted

GET /tests/{id}/results

Description

Get result data for specified test

URL structure
https://api.loadimpact.com/v2/tests/{id}/results
API Versions

2

Method

GET

Request

Sample request

curl -X GET "https://api.loadimpact.com/v2/tests/{id}/results" \
 -u "API_TOKEN:" 
Response
200

Sample response

{
    "__li_clients_active": [
        {
            "offset": 69855, 
            "timestamp": 96855, 
            "value": 84455
        }
    ], 
    "__li_user_load_time": [
        {
            "offset": 77279, 
            "timestamp": 67551, 
            "value": 69980
        }
    ]
}
Notes

The result data to return is dictated by the "ids" query string parameter. This parameter can contain any number of entries for specific metrics to retrieve. Each entry is separated by a comma and has the following format:

metric_id:load_zone_id...|start_offset:end_offset
Param Description Required?
metric_id The metric ID for which to retrieve result data. required
load_zone_id The ID of the load_zone from which to view data. If in doubt use 1, which means "World (Aggregated)". For a full list of load zone IDs see table below. required (except for log result data, "__li_log")
... Some metrics need extra parameters to describe exactly what data to retrieve. The full list of extra parameters are specified in the metric type specific sections below. For standard metrics load_zone_id is the last parameter. varies with metric type
start_offset Each metric data point contains an "offset" attribute that can be used to paginate/slice the metric result data. The start_offset specifies the start of the slice of data to retrieve. optional
end_offset Each metric data point contains an "offset" attribute that can be used to paginate/slice the metric result data. The end_offset specifies the end of the slice of data to retrieve. optional

The load zone IDs are as follows (note that result data is only available from the load zones actually used in a test):

ID Geographic region Service provider
1 World Aggregated
11 Ashburn, US Amazon
12 Palo Alto, US Amazon
13 Dublin, Ireland Amazon
14 Singapore Amazon
15 Tokyo, Japan Amazon
22 Portland, US Amazon
23 Sao Paulo, Brazil Amazon
25 Sydney, Australia Amazon
26 Chicago, US Rackspace
27 Dallas, US Rackspace
28 London, UK Rackspace
29 Sydney, Australia Rackspace
Thus, a full request URL might look something like this:
https://api.loadimpact.com/v2/tests/{id}/results?ids=__li_clients_active:1,__li_user_load_time:1|0:100
Data points

Each data point returned for a metric contains the two attributes "offset" and "timestamp". These two attributes represent an offset into the data series for a particular metric and the time of collection (UNIX epoch in microseconds). Note that the offset is strictly increasing but currently not guaranteed to be contiguous within a specific metric's data series.


Standard metrics

To retrieve result data for a standard metric you only need the metric ID and load zone ID:
metric_id:load_zone_id|start_offset:end_offset

The following standard metrics are available:
Metric ID Description Sample data point Unit
__li_accumulated_load_time The accumulated load time is the sum of all individual HTTP transaction load times during a script repetition. {"value": 1.0} Milliseconds
__li_bandwidth Bandwidth consumption throughout test. {"avg": 1.0} Bits/Seconds
__li_clients_active Number of concurrent users active throughout test. {"value": 1} Count
__li_connections_active Number of established TCP connections active throughout test. {"value": 1} Count
__li_content_type Content type name and count pairs seen throughout test. The count is the number of unique (test wide) URL and content type pairs seen since the last data point. {"content_types": {"text/html": 1, "application/json": 2}} Count per content type
__li_content_type_load_time Content type load times throughout test. {"content_type": "text/html", "count": 1, "max": 1.0, "avg": 1.0, "min": 1.0} Count and Milliseconds
__li_failure_rate The HTTP transaction failure rate throughout test. {"avg": 1.0} Percent
__li_live_feedback Progress information reported throughout test at different stages. The attributes provided in each data point varies depending on what "type" it is. The "country_code2" attribute, if present, is the 2-letter country code defined in ISO-3166-2 {"country_code2": "US", "msg": "Waiting for load generators...", "city": "Ashburn", "lat": 39.04, "percent": 100, "lng": -77.48, "type": "wait_for_loadgen", "load_zone_id": 11} Mixed
__li_loadgen_cpu_utilization The aggregate CPU utilization (expressed in percent) of the specified load zone. {"value": 1.0} Percent
__li_loadgen_memory_utilization The aggregate memory utilization (expressed in percent) of the specified load zone. {"value": 1.0} Percent
__li_log Log result data from log.error/info/debug calls in your load script. {"load_zone_id": 11, "user_scenario_id": 1, "level": "info", "message": "I'm a log message!"} Text
__li_progress_percent_total Progress of test in percent {"value": 1.0} Percent
__li_reps_failed_percent The number of failed user scenario script repetitions throughout test. {"value": 1, "percent": 1.0} Count and Percent
__li_reps_succeeded_percent The number of successful user scenario script repetitions throughout test. {"value": 1, "percent": 1.0} Count and Percent
__li_requests_per_second Requests per second metric {"avg": 1.0} Requests/Second
__li_total_rx_bytes The accumulated total number of received bytes throughout test. {"value": 1} Bytes
__li_total_requests The accumulated total number of HTTP requests made throughout test. {"value": 1} Count
__li_user_load_time User load time (time it takes to execute one repetition of a load script excluding sleep time) at given timestamps {"value": 1.0} Milliseconds

URL metrics

Result data for URLs is saved for each URL, load zone ID, user scenario ID, HTTP status code and HTTP method quintette. The metric ID for a URL is constructed as follows (in pseudo code):
metric_id = "__li_url_" + md5(url)

To retrieve result data for a specific quintette you need to add all the required extra parameters:
metric_id:load_zone_id:user_scenario_id:http_status_code:http_method|start_offset:end_offset

The extra parameters are as follows (all required):
Extra param Description
user_scenario_id The ID of the user scenario from which the request was made.
http_status_code The status code of the responses. Usually "200" (response OK) is a good default.
http_method The HTTP method used to make the request. Usually "GET" is a good default.
Sample data point

{"count": 1, "avg_cntlen": 387, "url": "http://www.example.com/", "status_code": 200, "comp_count": 0, "content_types": {"image/png": 1}, "min": 26.21, "max": 26.21, "avg_comp_cntlen": 0, "avg": 26.21, "method": "GET"}

Attribute Description Unit
avg,max,min The average, max and min load times of responses seen for this metric since last data point. Milliseconds
avg_cntlen The average content length of responses seen for this metric since last data point. Bytes
avg_comp_cntlen The average content length of responses seen for this metric since last data point. Bytes
comp_count The number of compressed responses seen for this metric since last data point. Count
content_types The different content types of responses seen for this metric since last data point. A web server might for example return a 503 HTML error page when stressed instead of serving an image. Count per content type
count Number of responses seen for this metric since last data point. Count
method The HTTP request method used. String
status_code The HTTP response status code returned by the server for this metric. String

Page metrics

Result data for pages is saved for each page name, load zone ID and user scenario ID triple. The metric ID for a page is constructed as follows (in pseudo code):
// The page_name is whatever you you passed in to your http.page_start(page_name) call in your load script.
metric_id = "__li_page_" + md5(page_name)

To retrieve result data for a specific triple you need to add all the required extra parameters:
metric_id:load_zone_id:user_scenario_id|start_offset:end_offset

The extra parameters are as follows (all required):
Extra param Description
user_scenario_id The ID of the user scenario where the relevant http.start_page() call was made.
Sample data point

{"count": 1, "name": "My page", "min": 0.72314, "max": 0.72314, "avg": 0.72314, "type": "seconds"}

Attribute Description Unit
avg,max,min The average, max and min load times of the page since last data point. Milliseconds
count Number of pages viewed/loaded since last data point. Count
name The name of the page as specified in the user scenario load script. String
type The unit of the data points for this metric, "seconds" for pages. String

Custom metrics

Result data for custom metrics is saved for each custom metrics name, load zone ID and user scenario ID triple. The metric ID for a custom metric is constructed as follows (in pseudo code):
// The custom_metric_name is whatever you passed in to your result.custom_metric(custom_metric_name) call in your load script.
metric_id = "__custom_" + md5(custom_metric_name)

To retrieve result data for a specific triple you need to add all the required extra parameters:
metric_id:load_zone_id:user_scenario_id|start_offset:end_offset

The extra parameters are as follows (all required):
Extra param Description
user_scenario_id The ID of the user scenario where the relevant result.custom_metric() call was made.
Sample data point

{"count": 1, "name": "My metric", "min": 0.35342, "max": 0.72314, "avg": 0.54736, "type": "number"}

Attribute Description Unit
avg,max,min The average, max and min values seen for this metric since last data point. Milliseconds
count Number of custom metrics seen since last data point. Count
name The name of the metric as specified in the user scenario load script. String
type The unit of the data points for this metric, defaults to "number". String

Server metrics

Result data for server metrics is saved for each server metrics agent name and server metric label. The metric ID for a server metric is constructed as follows (in pseudo code):
// The server_metric_agent_name is whatever you have decided to call your agent, see the agent_name server metrics agent setting.
// The server_metric_label is the label of an individual metric, see labels for the default server metrics in table below.
metric_id = "__server_metric_" + md5(server_metric_agent_name + server_metric_label)

Default server metric labels:
Metric label Description Sample data point
CPU CPU utilization data. {"count": 1, "name": "Web-1", "min": 0, "max": 1.0, "median": 1, "label": "CPU", "stddev": 0.0, "avg": 1.0, "unit": "%"}
Memusage Memory utilization data. {"count": 1, "name": "Web-1", "min": 0, "max": 1.0, "median": 1, "label": "Memusage", "stddev": 0.0, "avg": 1.0, "unit": "%"}
Disk Disk utilization data. {"count": 1, "name": "Web-1", "min": 0, "max": 1.0, "median": 1, "label": "Disk", "stddev": 0.0, "avg": 1.0, "unit": "%"}
Network Network bandwidth utilization data. {"count": 1, "name": "Web-1", "min": 0, "max": 1.0, "median": 1, "label": "Network", "stddev": 0.0, "avg": 1.0, "unit": "bps"}

To retrieve result data for a specific server metric you only need the metric ID:
metric_id|start_offset:end_offset

Test configurations


Operations for managing test configurations

GET /test-configs

Description

Retrieve test configurations associated with a user's account

URL structure
https://api.loadimpact.com/v2/test-configs
API Versions

2

Method

GET

Request

Sample request

curl -X GET "https://api.loadimpact.com/v2/test-configs" \
 -u "API_TOKEN:" 
Response
200

Sample response

[
    {
        "config": {
            "load_schedule": [
                {
                    "duration": 10, 
                    "users": 50
                }
            ], 
            "tracks": [
                {
                    "clips": [
                        {
                            "percent": 100, 
                            "user_scenario_id": 60385
                        }
                    ], 
                    "loadzone": "amazon:us:ashburn"
                }
            ], 
            "user_type": "sbu"
        }, 
        "created": "2016-11-30T11:19:33+00:00", 
        "id": 80008, 
        "name": "Name of resource", 
        "updated": "2016-11-30T11:19:33+00:00", 
        "url": "http://www.example.com/"
    }
]

POST /test-configs

Description

Create a test configuration

URL structure
https://api.loadimpact.com/v2/test-configs
API Versions

2

Method

POST

Request

Body (application/json)

  • String name required Name of test configuration
  • String url required Main target url of test
  • JSON config required Test configuration (unit of duration is minutes)

Sample request

curl -X POST https://api.loadimpact.com/v2/test-configs -u "API_TOKEN:" \
    -H "Content-Type: application/json" \
    -d '{
        "config": {
            "load_schedule": [
                {
                    "duration": 10,
                    "users": 50
                }
            ],
            "tracks": [
                {
                    "clips": [
                        {
                            "percent": 100,
                            "user_scenario_id": 51184
                        }
                    ],
                    "loadzone": "amazon:us:ashburn"
                }
            ],
            "user_type": "sbu"
        },
        "name": "Name of resource",
        "url": "http://www.example.com/"
    }'
Response
201

Sample response

{
    "config": {
        "load_schedule": [
            {
                "duration": 10, 
                "users": 50
            }
        ], 
        "tracks": [
            {
                "clips": [
                    {
                        "percent": 100, 
                        "user_scenario_id": 80570
                    }
                ], 
                "loadzone": "amazon:us:ashburn"
            }
        ], 
        "user_type": "sbu"
    }, 
    "created": "2016-11-30T11:19:33+00:00", 
    "id": 51310, 
    "name": "Name of resource", 
    "updated": "2016-11-30T11:19:33+00:00", 
    "url": "http://www.example.com/"
}
Notes

The unit of "duration" properties is minutes

GET /test-configs/{id}

Description

Retrieve specified test configuration

URL structure
https://api.loadimpact.com/v2/test-configs/{id}
API Versions

2

Method

GET

Request

Sample request

curl -X GET "https://api.loadimpact.com/v2/test-configs/{id}" \
 -u "API_TOKEN:" 
Response
200

Sample response

{
    "config": {
        "load_schedule": [
            {
                "duration": 10, 
                "users": 50
            }
        ], 
        "tracks": [
            {
                "clips": [
                    {
                        "percent": 100, 
                        "user_scenario_id": 81008
                    }
                ], 
                "loadzone": "amazon:us:ashburn"
            }
        ], 
        "user_type": "sbu"
    }, 
    "created": "2016-11-30T11:19:33+00:00", 
    "id": 86984, 
    "name": "Name of resource", 
    "updated": "2016-11-30T11:19:33+00:00", 
    "url": "http://www.example.com/"
}

PUT /test-configs/{id}

Description

Update the specified test configuration

URL structure
https://api.loadimpact.com/v2/test-configs/{id}
API Versions

2

Method

PUT

Request

Body (application/json)

  • String name Name of test configuration
  • String url Main target url of test
  • JSON config Test configuration

Sample request

curl -X PUT https://api.loadimpact.com/v2/test-configs/{id} -u "API_TOKEN:" \
    -H "Content-Type: application/json" \
    -d '{
        "config": {
            "load_schedule": [
                {
                    "duration": 10,
                    "users": 50
                }
            ],
            "tracks": [
                {
                    "clips": [
                        {
                            "percent": 100,
                            "user_scenario_id": 65706
                        }
                    ],
                    "loadzone": "amazon:us:ashburn"
                }
            ],
            "user_type": "sbu"
        },
        "name": "Name of resource"
    }'
Response
200

Sample response

{
    "config": {
        "load_schedule": [
            {
                "duration": 10, 
                "users": 50
            }
        ], 
        "tracks": [
            {
                "clips": [
                    {
                        "percent": 100, 
                        "user_scenario_id": 83959
                    }
                ], 
                "loadzone": "amazon:us:ashburn"
            }
        ], 
        "user_type": "sbu"
    }, 
    "created": "2016-11-30T11:19:33+00:00", 
    "id": 79568, 
    "name": "Name of resource", 
    "updated": "2016-11-30T11:19:33+00:00", 
    "url": "http://www.example.com/"
}

DELETE /test-configs/{id}

Description

Delete the specified test configuration

URL structure
https://api.loadimpact.com/v2/test-configs/{id}
API Versions

2

Method

DELETE

Request

Sample request

curl -X DELETE "https://api.loadimpact.com/v2/test-configs/{id}" \
 -u "API_TOKEN:" 
Response
204

POST /test-configs/{id}/clone

Description

Clone the specified test configuration and give it a new name

URL structure
https://api.loadimpact.com/v2/test-configs/{id}/clone
API Versions

2

Method

POST

Request

Body (application/json)

  • String name required Name of the cloned test configuration

Sample request

curl -X POST "https://api.loadimpact.com/v2/test-configs/{id}/clone" \
    -u "API_TOKEN:" \
    -H "Content-Type: application/json" \
    -d '{"name": "New resource name"}'
Response
201

Sample response

{
    "config": {
        "load_schedule": [
            {
                "duration": 10, 
                "users": 50
            }
        ], 
        "tracks": [
            {
                "clips": [
                    {
                        "percent": 100, 
                        "user_scenario_id": 54468
                    }
                ], 
                "loadzone": "amazon:us:ashburn"
            }
        ], 
        "user_type": "sbu"
    }, 
    "created": "2016-11-30T11:19:33+00:00", 
    "id": 65638, 
    "name": "Name of resource", 
    "updated": "2016-11-30T11:19:33+00:00", 
    "url": "http://www.example.com/"
}

POST /test-configs/{id}/start

Description

Start a test based on the specified test configuration

URL structure
https://api.loadimpact.com/v2/test-configs/{id}/start
API Versions

2

Method

POST

Request

Sample request

curl -X POST "https://api.loadimpact.com/v2/test-configs/{id}/start" \
 -u "API_TOKEN:" 
Response
201

Sample response

{
    "id": 83452
}

User scenarios


Operations for managing user scenarios

GET /user-scenarios

Description

Retrieve user scenarios associated with a user's account

URL structure
https://api.loadimpact.com/v2/user-scenarios
API Versions

2

Method

GET

Request

Sample request

curl -X GET "https://api.loadimpact.com/v2/user-scenarios" \
 -u "API_TOKEN:" 
Response

Sample response

[
    {
        "created": "2016-11-30T11:19:33+00:00", 
        "id": 52174, 
        "load_script": "I'm a string", 
        "name": "Name of resource", 
        "script_type": "lua", 
        "updated": "2016-11-30T11:19:33+00:00"
    }
]

POST /user-scenarios

Description

Create user scenario

URL structure
https://api.loadimpact.com/v2/user-scenarios
API Versions

2

Method

POST

Request

Body (application/json)

  • String name required Name of user scenario
  • String load_script required Lua load script
  • UserScenarioDataStoreList data_stores List of data stores to associate with user scenario

Sample request

curl -X POST https://api.loadimpact.com/v2/user-scenarios -u "API_TOKEN:" \
    -H "Content-Type: application/json" \
    -d '{
        "load_script": "I am a string",
        "name": "Name of resource",
        "data_stores": [1]
    }'
Response
201

Sample response

{
    "created": "2016-11-30T11:19:33+00:00", 
    "id": 82431, 
    "load_script": "I'm a string", 
    "name": "Name of resource", 
    "script_type": "lua", 
    "updated": "2016-11-30T11:19:33+00:00"
}
Errors
  • 409 Duplicate, you already have a user scenario with specified name

GET /user-scenarios/{id}

Description

Retrieve specified user scenario

URL structure
https://api.loadimpact.com/v2/user-scenarios/{id}
API Versions

2

Method

GET

Request

Sample request

curl -X GET "https://api.loadimpact.com/v2/user-scenarios/{id}" \
 -u "API_TOKEN:" 
Response
200

Sample response

{
    "created": "2016-11-30T11:19:33+00:00", 
    "id": 77903, 
    "load_script": "I'm a string", 
    "name": "Name of resource", 
    "script_type": "lua", 
    "updated": "2016-11-30T11:19:33+00:00"
}

PUT /user-scenarios/{id}

Description

Update user scenario

URL structure
https://api.loadimpact.com/v2/user-scenarios/{id}
API Versions

2

Method

PUT

Request

Body (application/json)

  • String name Name of user scenario
  • String load_script Lua load script
  • UserScenarioDataStoreList data_stores List of data stores to associate with user scenario

Sample request

curl -X PUT https://api.loadimpact.com/v2/user-scenarios/{id} -u "API_TOKEN:" \
    -H "Content-Type: application/json" \
    -d '{
        "load_script": "I am a string",
        "name": "New resource name",
        "data_stores": [1]
    }'
Response
200

Sample response

{
    "created": "2016-11-30T11:19:33+00:00", 
    "id": 76011, 
    "load_script": "I'm a string", 
    "name": "Name of resource", 
    "script_type": "lua", 
    "updated": "2016-11-30T11:19:33+00:00"
}
Errors
  • 422 One of the provided data store IDs is considered invalid

DELETE /user-scenarios/{id}

Description

Delete specified user scenario

URL structure
https://api.loadimpact.com/v2/user-scenarios/{id}
API Versions

2

Method

DELETE

Request

Sample request

curl -X DELETE "https://api.loadimpact.com/v2/user-scenarios/{id}" \
 -u "API_TOKEN:" 
Response
204
Errors
  • 409 Unable to delete user scenario since it's being used by one or more test configurations

POST /user-scenarios/{id}/clone

Description

Clone the specified user scenario and give it a new name

URL structure
https://api.loadimpact.com/v2/user-scenarios/{id}/clone
API Versions

2

Method

POST

Request

Body (application/json)

  • String name required Name of the cloned user scenario

Sample request

curl -X POST https://api.loadimpact.com/v2/user-scenarios/{id}/clone -u "API_TOKEN:" \
    -H "Content-Type: application/json" \
    -d '{
        "name": "Name of resource"
    }'
Response
201

Sample response

{
    "created": "2016-11-30T11:19:33+00:00", 
    "id": 69899, 
    "load_script": "I'm a string", 
    "name": "Name of resource", 
    "script_type": "lua", 
    "updated": "2016-11-30T11:19:33+00:00"
}
Errors
  • 409 Duplicate, you already have a user scenario with specified name

User scenario validations


Operations for managing user scenario validations

POST /user-scenario-validations

Description

Create a user scenario validation given a user scenario ID.

URL structure
https://api.loadimpact.com/v2/user-scenario-validations
API Versions

2

Method

POST

Request

Body (application/json)

  • Int user_scenario_id required ID of the user scenario to be validated

Sample request

curl -X POST https://api.loadimpact.com/v2/user-scenario-validations -u "API_TOKEN:" \
    -H "Content-Type: application/json" \
    -d '{
        "user_scenario_id": 87109
    }'
Response
201

Sample response

{
    "created": "2016-11-30T11:19:33+00:00", 
    "ended": "2016-11-30T11:19:33+00:00", 
    "id": 63027, 
    "started": "2016-11-30T11:19:33+00:00", 
    "status": 0, 
    "status_text": "Queued", 
    "user_scenario_id": 96785
}
Errors
  • 429 You have reached the limit on how many validations you are allowed to run simultaneously, the limit is 3.
Notes

You are only allowed to have 3 simultaneous validations running at any given time.

GET /user-scenario-validations/{id}

Description

Retrieve user scenario validations associated with a user's account

URL structure
https://api.loadimpact.com/v2/user-scenario-validations/{id}
API Versions

2

Method

GET

Request

Sample request

curl -X GET "https://api.loadimpact.com/v2/user-scenario-validations/{id}" \
 -u "API_TOKEN:" 
Response
200

Sample response

{
    "created": "2016-11-30T11:19:33+00:00", 
    "ended": "2016-11-30T11:19:33+00:00", 
    "id": 85358, 
    "started": "2016-11-30T11:19:33+00:00", 
    "status": 0, 
    "status_text": "Queued", 
    "user_scenario_id": 62259
}
Notes

The status field can be one of the following values:

Status Description
0 Queued
1 Initializing
2 Running
3 Finished
4 Failed

GET /user-scenario-validations/{id}/results

Description

Get result data for specified user scenario validation

URL structure
https://api.loadimpact.com/v2/user-scenario-validations/{id}/results
API Versions

2

Method

GET

Request

Sample request

curl -X GET "https://api.loadimpact.com/v2/user-scenario-validations/{id}/results" \
 -u "API_TOKEN:" 
Response
200

Sample response

{
    "results": [
        {
            "message": "I'm a string", 
            "offset": 61281, 
            "timestamp": "2016-11-30T11:19:33+00:00", 
            "type": 0
        }
    ], 
    "status": 0, 
    "status_text": "Queued"
}