> OctoPerf load testing - OctoPerf Rest API documentation page. Link to OctoPerf Rest API url.

Source: https://api.octoperf.com/doc/runtime/edit-scenario/integrations-automation/ci-cd/rest/

# OctoPerf Rest API

Our REST API documentation is available at [https://api.octoperf.com/swagger-ui.html](https://api.octoperf.com/swagger-ui/index.html)

It gives you a programmatic access to all OctoPerf resources, from Virtual Users to Tests Reports.

!!! tip
    To get a real life example of a call to our API, simply use our UI while recording with the dev tools, exactly like a [virtual user recording](https://api.octoperf.com/doc/design/create-virtual-user/har-recorder/record-firefox-har/).

!!! warning
    Version `17.0.0` introduced breaking changes on the analysis endpoints, and test results recorded before that version answer empty until their data has been updated. If you already call our API, read [REST API changes: 16.2 to 17.0](https://api.octoperf.com/doc/api-changes-17.0/) before upgrading.

    Version `17.0.1` renamed a field of the Results Tree response - see [REST API changes: 17.0.0 to 17.0.1](https://api.octoperf.com/doc/api-changes-17.0.1/).

    Version `17.1.0` changes how task results are polled - see [REST API changes: 17.0.1 to 17.1.0](https://api.octoperf.com/doc/api-changes-17.1/).

    Version `18.0.0` changes the body of a Virtual User validation, and refuses to launch a scenario with an error in its [scenario check](https://api.octoperf.com/doc/runtime/edit-scenario/scenario-check/) - see [REST API changes: 17.1.0 to 18.0.0](https://api.octoperf.com/doc/api-changes-18.0/).

## Samples

### Starting a Test Using cURL

To to start a test you need to call the Scenarios.run endpoint:

```sh
curl --header "Authorization: Bearer <apiKey>" -v -X POST https://api.octoperf.com/runtime/scenarios/run/<scenarioId>
```

The following parameters must be set:

* __apiKey__: your API key can be found in [your profile](https://api.octoperf.com/doc/account/profile/#apikey), accessible from the Profile menu in OctoPerf (top right corner of the UI).
* __scenarioId__: the ID of the scenario you want to run.

To know the ID of the scenario simply open it in OctoPerf's UI. Its ID is the last one in the URL:

![Scenario ID](https://api.octoperf.com/doc/runtime/edit-scenario/integrations-automation/ci-cd/rest/img/scenario-id.png "Scenario ID")

### Checking a Scenario Before Running It

A scenario with an **Error** in its [scenario check](https://api.octoperf.com/doc/runtime/edit-scenario/scenario-check/) cannot run: the `run` call answers `400`, with a message that names the user profile and the problem, and no credit is consumed:

```
Scenario cannot run: Buyer in Paris: No agent running in this location
```

To see the problems before launching, call the sanity check endpoint. It runs nothing and consumes no credit:

```sh
curl --header "Authorization: Bearer <apiKey>" https://api.octoperf.com/runtime/scenarios/sanity-check/<scenarioId>
```

It answers the list of problems, the worst first, each with its `level` (`ERROR`, `WARNING` or `INFO`), its `errorMsg`, the `userProfileName` to fix, the `rule` it comes from and its `details`. An empty list means the scenario can run as configured. The [Scenario Check](https://api.octoperf.com/doc/runtime/edit-scenario/scenario-check/) page explains each `rule`: its section is the rule in lowercase, with dashes, for example `AGENT_MISSING` is explained in [No agent ready in this location](https://api.octoperf.com/doc/runtime/edit-scenario/scenario-check/#agent-missing).

!!! tip
    If you want to schedule a load test you can then use [crontab on Linux](http://man7.org/linux/man-pages/man5/crontab.5.html) or an [online scheduling service](https://cron-job.org/en/) to do it.

### Starting a Test with a template

It is possible to pass additional parameters to the previous `POST` request to select for instance the report template to be used.

But first we need to know the report template id, so we are going to execute the following request:

```sh
curl --header "Authorization: Bearer <apiKey>" -v -X GET https://api.octoperf.com/analysis/bench-report-templates/by-workspace/<workspaceId>
```

To find the `workspaceId` just look at the URL when you're inside the workspace:

![Workspace ID](https://api.octoperf.com/doc/runtime/edit-scenario/integrations-automation/ci-cd/rest/img/workspace-id.png "Workspace ID")

The result will be a list of all the templates of this workspace. Here with the `templateId` highlighted:

![Template ID](https://api.octoperf.com/doc/runtime/edit-scenario/integrations-automation/ci-cd/rest/img/template-id.png "Template ID")

Now you just want to run the same `POST` request than earlier but with the `templateId` specified like this:

```sh
curl --header "Authorization: Bearer <apiKey>" -v -X POST https://api.octoperf.com/runtime/scenarios/run/<scenarioId>?templateId=<templateId>
```

### Downloading a report

To download a report as a PDF file you will need:

* __apiKey__: your API key can be found in [your profile](https://api.octoperf.com/doc/account/profile/#apikey), accessible from the Profile menu in OctoPerf (top right corner of the UI).
* __reportId__: the ID of the report you want to print.

To know the ID of the report simply open it in OctoPerf's UI. Its ID is the last one in the URL:

![Report ID](https://api.octoperf.com/doc/runtime/edit-scenario/integrations-automation/ci-cd/rest/img/report-id.png "Report ID")

Then <a href="https://api.octoperf.com/doc/runtime/edit-scenario/integrations-automation/ci-cd/rest/img/download-report.sh" download>download this shell script (`download-report.sh`)</a> (more information about what the script does is available as inline comments).

Make it executable with `chmod +x download-report.sh` and execute it with `./download-report.sh <report ID> <API Key>`.