Overview
Tests is run by one or more test runners (also known as a “provider” in the API). Each provider runs the test in one or more regions. Each region has a set of agents which are responsible for running your tests.
Register agents by instance id in self-hosted region
Takes a comma separated list of instance ids and registers them as test runners in the self-hosted region specified.
POST /agents
Request Body
instanceIdsRequired: Comma separated list of instance ids to register.regionNameRequired: Name of the self-hosted region.regionDescription: Description of the the region.
Get list of all providers
Retrieve a list of all providers your credentials allow access to. This includes the public shared grid, private shared grid, and any on demand providers. If an organization id is specified, only providers within that organization are returned.
GET /providers
GET /orgs/:orgId/providers
Request Parameters
down: Whether to include all provider regions. Defaults to false.activeRegionsOnly: Ifdownistrue, whether or not to return the active regions only. If the region was created for an AWS on demand region, it will be marked inactive after the related test is completed. All shared grid regions are always active. Defaults to true.providerType: Filter for a certain type of provider only. Possible values:SharedandAwsOnDemand. If not specified, all provider types are returned.
Sample Response
[
{
"id":0,
"createdAt":"2016-05-06T13:56:53.328Z",
"updatedAt":"2016-05-06T13:56:53.328Z",
"name":"Public Shared Grid",
"public":true,
"providerType":"Shared",
"active":true
},
{
"id":5,
"createdAt":"2016-05-16T04:26:45.125Z",
"updatedAt":"2016-05-16T04:26:45.125Z",
"name":"AWS On Demand - Testable Account",
"public":true,
"providerType":"AwsOnDemand",
"active":true
},
{
"id":3,
"createdAt":"2016-05-06T14:14:42.251Z",
"updatedAt":"2016-05-06T14:14:42.251Z",
"name":"My Shared Grid",
"public":false,
"providerType":"Shared",
"organizationId":3,
"active":true
},
{
"id":12,
"createdAt":"2016-05-18T13:18:08.180Z",
"updatedAt":"2016-05-18T13:18:08.180Z",
"name":"AWS On Demand - My Account",
"public":false,
"providerType":"AwsOnDemand",
"organizationId":3,
"metadata":{
"awsAccessKeyId":"ABC",
"awsSecretAccessKey":"DEF"
},
"active":true
}
]
Get all running agent details
Retrieve details about all agents currently running globally to which you have access. This includes all agents running on public shared grid, your on premises private shared grid, and any on demand regions. If a region does not have any running agents, it will not appear in the results. If an organization id is specified, only providers within that organization are returned.
GET /providers/all/agents
GET /orgs/:orgId/providers/all/agents
Request Parameters
activeRegionsOnly: Ifdownistrue, whether or not to return the active regions only. If the region was created for an AWS on demand region, it will be marked inactive after the related test is completed. All shared grid regions are always active. Defaults to true.providerType: Filter for a certain type of provider only. Possible values:SharedandAwsOnDemand. If not specified, all provider types are returned.
Sample Response
{
"regions":[
{
"region":{
"id":1,
"createdAt":"2015-07-11T18:21:39.170Z",
"updatedAt":"2019-01-29T18:03:43.255Z",
"name":"aws-us-east-1",
"description":"AWS N. Virginia",
"active":true,
"isPaidExternally":false,
"location":{
"id":58,
"createdAt":"2018-01-15T05:33:13.213Z",
"updatedAt":"2019-01-29T18:03:43.254Z",
"name":"aws-us-east-1",
"latitude":39.0481,
"longitude":-77.4729,
"description":"AWS N. Virginia",
"provider":{
"id":0,
"createdAt":"2016-05-24T16:18:36.461Z",
"updatedAt":"2016-05-24T16:18:36.461Z",
"name":"Public Shared Grid",
"public":true,
"providerType":"Shared",
"metadata":{
},
"active":true,
"locations":[
],
"firstVersion":true
},
"regions":[
],
"firstVersion":false
},
"instances":[
],
"runningExecutions":[
],
"firstVersion":false
},
"totalCapacity":1999999998,
"availableCapacity":1999999998,
"numHosts":2,
"totalCpus":8,
"cpuUtilization":1,
"freeMemory":13672321024,
"totalMemory":16007544832,
"numAgents":2,
"agents":[
{
"id":"085e70c8-486f-4524-835a-26fb4c6d921c",
"regionId":1,
"pid":"",
"host":"ec2-54-211-48-163.compute-1.amazonaws.com",
"instanceId":"i-0c4xxxxxxx",
"isPaidExternally":false,
"containerId":"baae7e1aba1f79f218dadefac9b9867da78d18aa5118e0d0c33ec79e67ee557b",
"totalCapacity":999999999,
"availableCapacity":999999999,
"freeMemory":6824116224,
"totalMemory":8003772416,
"cpu":25.0,
"totalCpus":4,
"cpuUtilization":1,
"networkSent":9994,
"networkReceived":30976,
"disconnected":false,
"connections":68,
"version":"1.9.0",
"runningExecutions":[
]
}
]
}
]
}
Get running agents for provider
Same as the above GET /provider/all/agents except for the specified provider.
GET /providers/:id/agents
Request Parameters
activeRegionsOnly: Ifdownistrue, whether or not to return the active regions only. If the region was created for an AWS on demand region, it will be marked inactive after the related test is completed. All shared grid regions are always active. Defaults to true.
Get running agents for provider
Same as the above GET /provider/all/agents except for the specified provider + region.
GET /providers/:id/region/:regionId/agents
Get running agents for region
Same as the above GET /provider/:id/regions/:regionId/agents except without specifying the provider id directly.
GET /regions/:regionId/agents
Get region info by id or name
Gets the details of the region by id or name. This info includes the active agent and instance counts as well as a list of tests running in the region.
GET /orgs/:org/regions/:regionIdOrName
Example response:
{
"id": 12345,
"name": "load-test",
"description": "load-test",
"active": true,
"isPaidExternally": false,
"location": {
"id": 1231,
"name": "load-test",
"latitude": 39.0481,
"longitude": -77.4728,
"description": "load-test",
"provider": {
"id": 9999,
"createdAt": "2023-05-06T22:19:57.760Z",
"updatedAt": "2023-05-06T22:19:57.760Z",
"name": "My Shared Grid",
"public": false,
"providerType": "Shared",
"organizationId": 8888,
"metadata": {},
"active": true,
"locations": [],
"organizationSummary": {
"id": 8888,
"createdAt": "2023-05-06T22:19:57.731Z",
"updatedAt": "2023-05-06T22:19:57.732Z",
"name": "Example",
"email": "foo@acme.com",
"shared": true
},
"firstVersion": true
},
"regions": [],
"firstVersion": false
},
"instances": [],
"runningExecutions": [12345,12346],
"activeAgentCount": 10,
"instanceCount": 10,
"firstVersion": false
}
Create or update region
Create or update a region in private shared grid. If a region with the same name exists in your private shared grid it will simply update the description and return all details about that region.
POST /orgs/:orgId/regions
Request Body
nameRequired: Name of the the region.description: Description of the the region.
Example:
{
"name": "DC1",
"description": "On Prem in our DC1 location",
"providerId": 123
}
Sample Response
{
"id":111,
"createdAt":"2015-07-11T18:21:39.170Z",
"updatedAt":"2019-01-29T18:03:43.255Z",
"name":"DC1",
"description":"On Prem in our DC1 location",
"active":true,
"isPaidExternally":false,
"location":{
"id":58,
"createdAt":"2018-01-15T05:33:13.213Z",
"updatedAt":"2019-01-29T18:03:43.254Z",
"name":"DC1",
"latitude":39.0481,
"longitude":-77.4729,
"description":"On Prem in our DC1 location",
"provider":{
"id":111,
"createdAt":"2016-05-24T16:18:36.461Z",
"updatedAt":"2016-05-24T16:18:36.461Z",
"name":"Private Shared Grid",
"public":true,
"providerType":"Shared",
"active":true,
"firstVersion":true
}
}
}
Search for agent by instance id or host name
Search for test runners by instance id or host name.
GET /agents?q=[search]
Request Parameters
q: Comma separated list of instance IDs and/or host names. Finds any registered running agent in those regions.includeInactive: Whether to include previously registered agents that are no longer running in the results. Defaults tofalse.
Sample Response
[
{
"id":30415,
"createdAt":"2019-01-29T15:07:22.214Z",
"updatedAt":"2019-01-29T15:48:18.692Z",
"name":"c994f789-4614-4b57-bb1f-21e8a4eceaa0",
"host":"ec2-18-232-63-123.compute-1.amazonaws.com",
"instanceId":"i-072c9385cd304b4d4",
"isPaidExternally":false,
"active":true,
"version":"1.9.0",
"region":{
"id":3388,
"createdAt":"2018-06-05T03:45:41.100Z",
"updatedAt":"2019-01-29T15:47:29.061Z",
"name":"demo-region",
"description":"demo-region",
"active":true,
"isPaidExternally":false,
"location":{
"id":81,
"createdAt":"2018-06-05T03:45:40.998Z",
"updatedAt":"2019-01-29T15:47:29.059Z",
"name":"demo-region",
"latitude":39.0481,
"longitude":-77.4729,
"description":"demo-region",
"provider":{
"id":10,
"createdAt":"2016-10-07T04:14:51.264Z",
"updatedAt":"2016-10-07T04:14:51.264Z",
"name":"My Shared Grid",
"public":false,
"providerType":"Shared",
"organizationId":64,
"active":true
}
}
}
}
]
Register shared agent in region
Register a test runner agent in a private shared grid region.
PUT /agents/:agentId
The agentId is the id attribute of the agent returned from an agent search
Request Body
regionIdsRequired: An array of regions to associate with the agent, using region IDs.
Example:
{
"regionIds": [ 123 ],
}
Sample Response
{
"id": 111,
"createdAt": "2019-01-29T15:07:22.214Z",
"updatedAt": "2019-01-29T15:43:28.794Z",
"name": "c994f789-4614-4b57-bb1f-21e8a4eceaa0",
"host": "xxxx.amazonaws.com",
"instanceId": "i-072c9385cd304b4d4",
"isPaidExternally": false,
"active": true,
"version": "1.9.0",
"regions": [ {
"id": 3388,
"createdAt": "2018-06-05T03:45:41.100Z",
"updatedAt": "2018-10-23T14:39:32.839Z",
"name": "demo-region",
"description": "demo-region",
"active": true,
"isPaidExternally": false,
"location": {
"id": 115,
"createdAt": "2018-06-05T03:45:40.998Z",
"updatedAt": "2018-10-23T14:39:32.838Z",
"name": "demo-region",
"latitude": 39.0481,
"longitude": -77.4729,
"description": "demo-region",
"provider": {
"id": 112,
"createdAt": "2016-10-07T04:14:51.264Z",
"updatedAt": "2016-10-07T04:14:51.264Z",
"name": "My Shared Grid",
"public": false,
"providerType": "Shared",
"organizationId": 64,
"metadata": {},
"active": true,
"locations": [],
"firstVersion": true
}
}
} ]
}
Get provider details
Get details about the specified provider
GET /providers/:id
Request Parameters
down: Whether to include all provider regions. Defaults to true.activeRegionsOnly: Ifdownistrue, whether or not to return the active regions only. If the region was created for an AWS on demand region, it will be marked inactive after the related test is completed. All shared grid regions are always active. Defaults to true.
Sample Response
{
"id":12,
"createdAt":"2016-05-18T13:18:08.180Z",
"updatedAt":"2016-05-18T13:18:08.180Z",
"name":"AWS On Demand - My Account",
"public":false,
"providerType":"AwsOnDemand",
"organizationId":3,
"metadata":{
"awsAccessKeyId":"ABC",
"awsSecretAccessKey":"DEF"
},
"active":true,
"regions":[
{
"id":22,
"createdAt":"2016-05-19T21:09:11.341Z",
"updatedAt":"2016-05-19T21:12:33.028Z",
"name":"exec-1211-us-east-1",
"latitude":39.018,
"longitude":-77.539,
"description":"AWS",
"active":true
},
{
"id":31,
"createdAt":"2016-05-20T05:45:03.987Z",
"updatedAt":"2016-05-20T05:48:25.209Z",
"name":"exec-1220-us-east-1",
"latitude":39.018,
"longitude":-77.539,
"description":"AWS",
"active":true
}
]
}
Create provider
Create a new provider. A provider is also known as a test runner and is what actually allocates and runs your test.
POST /providers
Request Body
nameRequired: Name of the configuration.organizationIdRequired: Organization to which this provider belongs. This can be found using theGET /login?key=<abc>with your API key.providerTypeRequired: Possible values areSharedandAwsOnDemand. A private shared provider is created automatically the first time you run an on premises agent.metadata: An object containing provider specific details. For AWS on demand providers this includesawsAccessKeyIdandawsSecretAccessKey.
Example:
{
"name": "AWS On Demand - My Account",
"organization": 3,
"providerType": "AwsOnDemand",
"providers":{
"awsAccessKeyId": "abc",
"awsSecretAccessKey": "def"
}
}
Sample Response
{
"id":12,
"createdAt":"2016-05-18T13:18:08.180Z",
"updatedAt":"2016-05-18T13:18:08.180Z",
"name":"AWS On Demand - My Account",
"public":false,
"providerType":"AwsOnDemand",
"organizationId":3,
"metadata":{
"awsAccessKeyId":"abc",
"awsSecretAccessKey":"def"
},
"active":true
}
Update provider
Update the provider parameters. All parameters available when creating can be specified during update except providerType and organizationId.
PUT /providers/:id
Request Body
{
"name": "New Name",
"metadata": {
"awsAccessKeyId": "newabc",
"awsSecretAccessKey": "newdef"
}
}
Response
{
"id":12,
"createdAt":"2016-05-18T13:18:08.180Z",
"updatedAt":"2016-05-18T13:18:08.180Z",
"name":"AWS On Demand - My Account",
"public":false,
"providerType":"AwsOnDemand",
"organizationId":3,
"metadata":{
"awsAccessKeyId":"newabc",
"awsSecretAccessKey":"newdef"
},
"active":true
}
Delete provider
DELETE /providers/:id
Response
The deleted provider
{
"id":12,
"createdAt":"2016-05-18T13:18:08.180Z",
"updatedAt":"2016-05-18T13:18:08.180Z",
"name":"AWS On Demand - My Account",
"public":false,
"providerType":"AwsOnDemand",
"organizationId":3,
"metadata":{
"awsAccessKeyId":"newabc",
"awsSecretAccessKey":"newdef"
},
"active":true
}
Deactivate Region
Remove a self-hosted region from being visible on Testable. Requires all test runner agents in the region to be stopped.
PUT /regions/:id
Request Body
{
"active": false
}
Get test runner AMIs
Get the AMI identifiers for one or more AWS regions.
GET /aws/amis
Request Parameters
regions: Comma separated list of AWS regions (e.g. us-east-1,eu-central-1)
Sample Response
[
{
"region": "eu-central-1",
"ami": {
"linux": "ami-06f879366ff1f5fac",
"windows": "ami-0830f96d3be6bbac2"
}
},
{
"region": "us-east-1",
"ami": {
"linux": "ami-0319a58ad01b96cb5",
"windows": "ami-0281073560940fddb"
}
}
]