Skip to content

REST API changes: 17.1.0 to 18.0.0

This page lists the changes to the OctoPerf REST API between 17.1.0 and 18.0.0. It is written for the people who call the API directly - CI/CD pipelines, custom reporting jobs, in-house dashboards. If you only use the web interface, the Maven plugin or the MCP server, you have nothing to do: they were updated with the platform.

If you are upgrading from 17.0.1 or earlier, read REST API changes: 17.0.1 to 17.1.0 first, then this page.

18.0.0 brings K6 as a new load engine. One change requires an update on your side: running a Virtual User validation takes a new body. Everything else is additive, but new enum values show in the responses: a client that refuses unknown enum values must learn them.

1. TL;DR: what changes

# Change Impact
1 POST /runtime/virtual-user-checks/{projectId}/{virtualUserId} takes a VirtualUserCheckSettings body; the route with {providerId}/{location} is removed Update your validation calls
2 New GET and DELETE /runtime/virtual-user-check-settings/{projectId}/{virtualUserId} Additive
3 New POST /design/imports/k6/{projectId} Additive
4 New POST /runtime/scenarios/k6/{projectId} Additive
5 PUT /design/virtual-users/sample/{projectId} accepts ?type=K6 and ?type=PLAYWRIGHT Additive
6 The Virtual User exports accept K6 Virtual Users Additive
7 TableEntry gains sampleType Additive
8 HttpResponseEntity gains failed Additive
9 New types and enum values: K6, K6ScriptAction, K6UserProfileEngine, CUSTOM, K6_RUNTIME... Check strict enum parsing
10 New GET /design/sla-profiles/threshold-defaults/custom-metrics; an SLA threshold can target a CUSTOM metric Additive

2. Running a Virtual User validation

A validation now runs with the settings of its own, the ones the validation panel shows: provider, location, iterations and the engine settings of a user profile. They are saved as the validation settings of the Virtual User at each run.

Removed:

  • POST /runtime/virtual-user-checks/{projectId}/{virtualUserId}/{providerId}/{location}?iterations=, with a BrowserSettings body,
  • the UserProfile body and the iterations query parameter of POST /runtime/virtual-user-checks/{projectId}/{virtualUserId}.

Now:

POST /runtime/virtual-user-checks/{projectId}/{virtualUserId}
Content-Type: application/json

{
  "projectId": "<projectId>",
  "virtualUserId": "<virtualUserId>",
  "providerId": "<providerId>",
  "location": "<location>",
  "iterations": 1,
  "engine": { "@type": "JmeterUserProfileEngine", ... }
}
  • projectId and virtualUserId must be those of the path: a mismatch answers 400.
  • iterations moves from the query to the body.
  • engine is the engine of a user profile: JmeterUserProfileEngine, PlaywrightUserProfileEngine, SeleniumUserProfileEngine or K6UserProfileEngine, matching the type of the Virtual User.
  • The response is still the BenchResult of the validation.

What to do. Read the saved settings first (§3), change what you need, and post them back:

curl -s -H "Authorization: Bearer ${TOKEN}" \
  "https://api.octoperf.com/runtime/virtual-user-check-settings/${PROJECT_ID}/${VU_ID}" > settings.json
curl -s -X POST -H "Authorization: Bearer ${TOKEN}" -H "Content-Type: application/json" \
  --data @settings.json \
  "https://api.octoperf.com/runtime/virtual-user-checks/${PROJECT_ID}/${VU_ID}"

3. Validation settings

Method Path Does
GET /runtime/virtual-user-check-settings/{projectId}/{virtualUserId} Returns the saved VirtualUserCheckSettings of the Virtual User, or the defaults of its type when none were saved
DELETE /runtime/virtual-user-check-settings/{projectId}/{virtualUserId} Forgets the saved settings: the next GET returns the defaults

There is no POST or PUT: running a validation saves its settings.

4. K6

Import K6 scripts

POST /design/imports/k6/{projectId}
Content-Type: multipart/form-data

One files part per script, .js or .ts, at least one. The first file is the entrypoint. The response is the created VirtualUser, of type K6.

Create a scenario from the K6 options

POST /runtime/scenarios/k6/{projectId}
Content-Type: application/json

{
  "virtualUserId": "<virtualUserId>",
  "entrypointFileName": "script.js",
  "providerId": "<providerId>",
  "location": "<location>",
  "name": "Scenario",
  "options": { "scenarios": { ... } }
}
  • options is the JSON output of k6 inspect --execution-requirements <entrypoint>.
  • entrypointFileName and name are optional.
  • The response is a K6ScenarioConversion: scenario, absent when no K6 scenario could be converted, and unconverted, one {scenario, kind, outcome} entry for each part of the load that did not convert as it is.

Samples and exports

  • PUT /design/virtual-users/sample/{projectId} takes an optional type, JMETER (the default), K6 or PLAYWRIGHT, to create the sample K6 or Playwright Virtual User. The Playwright sample is attached to the project's Core Web Vitals SLA profile, created when the project has none.
  • GET /design/exports/{virtualUserId} and GET /design/exports/all/{projectId}?vuType=K6 export K6 Virtual Users, as a ZIP file of their scripts.

5. Additive changes

TableEntry.sampleType

The rows of a statistic table carry the sample type they were computed from, CUSTOM for a custom metric:

{ "actionPath": "...", "sampleType": "BASIC", "values": { ... } }

HttpResponseEntity.failed

The responses of the validation and error exchanges carry failed, true when the engine counted the exchange as an error, a failed assertion on a 200 response included: the status alone cannot tell. false on a response stored before 18.0.0.

SLA thresholds on custom metrics

An SLAMonitorThreshold can target a custom metric: a CUSTOM_* metric of type CUSTOM, narrowed to one name by a metricName filter, its unit given by a UnitReportConfig. Such a threshold is evaluated on the whole Virtual User, when its SLAProfileAction sits at the root of the Virtual User.

{
  "@type": "SLAMonitorThreshold",
  "metric": {
    "id": "CUSTOM_AVG", "type": "CUSTOM", "benchResultId": "",
    "filters": [{"@type": "SingleTermFilter", "field": "metricName", "term": "LCP"}],
    "configs": [{"@type": "UnitReportConfig", "unit": "TIME"}]
  },
  "thresholds": []
}

GET /design/sla-profiles/threshold-defaults/custom-metrics returns the default thresholds of the custom metrics whose meaning is known, keyed by name: the Core Web Vitals LCP, INP, CLS, FCP and TTFB, on Google's bands.

New types and enum values

Where New value Meaning
VirtualUserType K6 A Virtual User made of K6 scripts
Action @type K6ScriptAction {id, name, enabled, fileName, script}: one file of a K6 Virtual User
UserProfile.engine @type K6UserProfileEngine The K6 settings of a user profile ; abortOnFail, false when absent, lets a threshold declaring abortOnFail stop K6 on its load generator
SampleType CUSTOM The custom metrics of the scripts
MetricId CUSTOM_AVG, CUSTOM_MIN, CUSTOM_MAX, CUSTOM_SUM, CUSTOM_COUNT, CUSTOM_RATE The statistics of a custom metric
MetricId PROTOCOL_MESSAGES The messages of a gRPC stream, a WebSocket session or a Kafka call
HttpProtocol SQL, REDIS, KAFKA The protocols of the K6 extensions
MonitorType K6_RUNTIME The K6 Runtime monitor of a K6 load generator
Report filter keys engine, k6SampleType, metricName Filter by engine, by K6 sample type, by custom metric

6. Migration checklist

  1. Post a VirtualUserCheckSettings body to run a validation, and stop calling the route with {providerId}/{location} (§2).
  2. Accept the new enum values in the responses you parse (§5).