Our API enables you to build your own way of integrating to our service.

Authentication

For added security, you can require a Project API key for all requests. You can enable the use of the API key under Settings->Project->Require key for API access.

The key should be then added to all request urls

Example URL with key https://api.usetrace.com/api/command/?key=<Project API key>

Commands

POST execute_all

Execute a number of traces defined by tags.

POST https://api.usetrace.com/api/project/<PROJECT_ID>/execute_all

You will find the PROJECT_ID from Settings.

Required arguments:

  • requiredCapabilities: array containing the required capabilities as objects

  • browserName: string the name of the browser, can be one of: chrome, firefox, internet explorer

  • version: number the version of the browser, only required for internet explorer

Optional arguments:

  • baseUrl: string the baseUrl to execute against (defaults to the project baseUrl)

  • tags: array run only traces with these tags (by default runs all traces)

  • commit: string a hash of the commit leading to this build

  • commitLink: string a link to the commit

  • parameters: object trace parameters

Return value: BATCH_ID - this can be used to poll for results.

Example JSON

{
    "baseUrl": "http://google.com",
    "requiredCapabilities": [
        {"browserName": "chrome"},
        {"browserName": "firefox"}
    ],
    "tags": ["smoke"],
    "commit": "abc123",
    "commitLink": "https://gitgit.git/git/abc123",
    "parameters": {
        "username": "Arto",
        "password": "mysecret"
    }
}

Example bash script

curl -H "Content-type: application/json" -d \
  "{\"commit\": \"$CI_COMMIT_ID\",
    \"commitLink\": \"$CI_BUILD_URL\",
    \"baseUrl\": \"http://google.com\",
    \"tags\": [],
    \"parameters\": {
        \"username\": \"Arto\",
        \"password\": \"mysecret\"
    }
    \"requiredCapabilities\":
        [{\"browserName\": \"chrome\"},
         {\"browserName\": \"firefox\"}]}" http://api.usetrace.com/api/project//execute_all

Example Windows PowerShell script

Requires PowerShell version 3 or higher.

$projectId = "YOUR-PROJECT-ID"
$startBatchResource = "http://api.usetrace.com/api/project/$projectId/execute_all"
$startBatchRequest = @"
{
    "requiredCapabilities":[
        {"browserName":"chrome"},
        {"browserName":"firefox"}
    ],
    "tags":["smoke"]
}
"@Invoke-RestMethod -ContentType "application/json" -Method Post -Uri $startBatchResource -Body $startBatchRequest

POST execute

Execute one trace.

POST https://api.usetrace.com/api/trace/<TRACE_ID>/execute

You will find a TRACE_ID from the browser’s URL bar when you are editing a trace.

Required arguments:

  • requiredCapabilities: array containing the required capabilities as objects

  • browserName: string the name of the browser, can be one of:  chrome, firefox, internet explorer

  • version: number the version of the browser, only required for internet explorer

Optional arguments:

  • baseUrl: string the baseUrl to execute against (defaults to the project baseUrl)

  • parameters: object trace parameters

Return value: BATCH_ID - this can be used to poll for results.

Example JSON

{
    "baseUrl": "http://google.com",
    "requiredCapabilities": [
        {"browserName": "chrome"},
        {"browserName": "firefox"}
    ]
}

Example bash script

curl -H "Content-type: application/json" -d \
  "{\"baseUrl\": \"http://google.com\",
    \"requiredCapabilities\":
        [{\"browserName\": \"chrome\"},
         {\"browserName\": \"firefox\"}]}" http://api.usetrace.com/api/trace//execute

Example Windows PowerShell script

Requires PowerShell version 3 or higher.

$traceId = "YOUR-TRACE-ID"
$runTraceResource = "http://api.usetrace.com/api/trace/$traceId/execute"
$runTraceRequest = @"
{
    "baseUrl": "http://google.com",
    "requiredCapabilities":[
        {"browserName":"chrome"},
        {"browserName":"firefox"}
    ]
}
"@Invoke-RestMethod -ContentType "application/json" -Method Post -Uri $runTraceResource -Body $runTraceRequest

Example Python script

import json
import requestsurl = 'https://api.usetrace.com/api/trace//execute'payload = {
    'baseUrl': 'http://google.com',
    'requiredCapabilities': [{"browserName": "chrome"}]
}
headers = {'content-type': 'application/json'}r = requests.post(url, data=json.dumps(payload), headers=headers)print(r)
print(r.content)

GET results

Poll for trace results. This command returns with HTTP status code 404 until the results are ready.

GET https://api.usetrace.com/api/results/<BATCH_ID>/xunit

The BATCH_ID is returned by execute_all or execute commands.

Return value: XML - xUnit-compatible trace results.

GET export

Get machine-readable dump of your project’s traces.

GET https://api.usetrace.com/api/export/<PROJECT_ID>/json

You will find the PROJECT_ID from Settings.

Return value: JSON - project’s trace dump.

GET lastBatchStatus

GET https://api.usetrace.com/api/project/<PROJECT_ID>/lastBatchStatus

Query for last batch results, conditionally filtered by tags.

Query parameters:

  • key: Required if enabled from settings.

  • maxAge: Maximum age of results to accept, in minutes. Min 5. Max 60247 = 7 days. Default 1560 = 26h if omitted.

  • tag: Only match batches with exactly these tags. Multiple tags specified as tag=foo&tag=bar. If omitted, no tag restriction is applied.

  • httpStatus: 1 If included and specified as ‘1’, the endpoint will respond with 404 HTTP status code if the batch contains any fails or timeouts, or if a batch is not found. If omitted or not specified as ‘1’, the endpoint will respond with 200 HTTP status code when it’s able to respond to the request. The response body may then be parsed and interpreted to find out the status.

API feedback

Any questions or improvement suggestions can be mailed to team@usetrace.com.

Did this answer your question?