k6-manage

Grafana Cloud k6 — interaction reference

The default path is the gcx CLI. When gcx isn't installed, every
endpoint here is still reachable via direct curl against k6's public
hosts — see §1.2 for the auth-header and host-translation rules. Two
principles shape the rest:

• gcx owns Grafana-side auth (when present). It injects the right
  headers on every call, so you should not set auth headers yourself.
  The only header you ever set by hand is X-K6TestRun-Id, on Loki
  log queries (§4), browser screenshot/file fetches (§6), and Tempo
  trace queries (§7) — anything else gets overwritten or causes
  conflicts. In curl mode the auth headers are manual; see §1.2.
• Reach for gcx k6 ... subcommands first. They wrap the common
  paths with friendlier ergonomics and handle pagination. Discover
  what's available with gcx help-tree k6 (and drill in further with
  gcx help-tree k6 <subcommand>); fall back to gcx api only when
  no subcommand exists for what you need.

---

1. Authentication

1.1 With gcx (default)

gcx login --context <ctx>                # one-time OAuth, browser flow
gcx --context <ctx> config check         # expect "✔ Connectivity: online"

Once a context is logged in, every gcx api ... and gcx k6 ... call
inherits its auth state. If a call returns "Invalid or expired token —
run gcx login to refresh", the OAuth session has lapsed — re-run
gcx login --context <ctx>.

1.2 Without gcx — direct curl

Check command -v gcx first. If it's missing, every endpoint in this
skill is still reachable directly against k6's public hosts — three
things change versus the gcx examples elsewhere:

• Auth headers are manual. Set both on every call:
  • Authorization: Bearer <k6_token>
  • X-Stack-ID: <int>
• Hosts replace the plugin proxy.
  • REST (/cloud/v6/..., /cloud/v5/..., /cloud-resources/v1/...,
    /insights/...) → https://api.k6.io
  • Logs (Loki) and traces (Tempo) → https://cloudlogs.k6.io
• No /api/plugins/k6-app/resources/{cloud,logs,insights} prefix.
  Drop it; everything after that prefix in the gcx examples is the
  real k6 path. The doubled cloud/cloud/ quirk from §2 collapses to
  a single /cloud/ — the first one was just the proxy route.

Obtaining the credentials

Don't guess these — prompt the user once per session for:

1. k6 API token — long-lived bearer; the same value
   gcx k6 auth token would print when gcx is configured.

2. Stack — either the integer stack ID (used directly in
   X-Stack-ID) or a Grafana stack URL (e.g.
   https://myorg.grafana.net). If the user supplies a URL, resolve
   it to an ID once with GET /cloud/v6/auth, which takes the URL in
   the X-Stack-Url header and returns {stack_id, default_project_id}:

   STACK_ID=$(curl -sS https://api.k6.io/cloud/v6/auth \
     -H "Authorization: Bearer $K6_TOKEN" \
     -H "X-Stack-Url: $STACK_URL" \
     | jq -r '.stack_id')
   

   Cache the resolved ID for the session — every subsequent call
   needs it in X-Stack-ID. (Note: /cloud/v6/auth is the only
   endpoint that takes X-Stack-Url instead of X-Stack-ID — it's
   how you cross the gap from "user-known URL" to "API-required ID".)

Translation cheat-sheet

gcx form (plugin proxy)	curl form (direct)
gcx api /api/plugins/k6-app/resources/cloud/cloud/v6/test_runs/123	curl https://api.k6.io/cloud/v6/test_runs/123 -H ...
gcx api /api/plugins/k6-app/resources/cloud/cloud/v5/test_runs/<id>/metrics	curl https://api.k6.io/cloud/v5/test_runs/<id>/metrics -H ...
gcx api /api/plugins/k6-app/resources/cloud/cloud-resources/v1/files/index	curl https://api.k6.io/cloud-resources/v1/files/index -H ...
gcx api /api/plugins/k6-app/resources/insights/insights/api/v1/testrun/<id>/executions	curl https://api.k6.io/insights/api/v1/testrun/<id>/executions -H ...
gcx api /api/plugins/k6-app/resources/logs/api/v1/query_range?...	curl https://cloudlogs.k6.io/api/v1/query_range?... -H ...
gcx api /api/plugins/k6-app/resources/logs/api/v1/tempo/api/search?...	curl https://cloudlogs.k6.io/api/v1/tempo/api/search?... -H ...

In every -H ... slot above, send both auth headers:
-H "Authorization: Bearer $K6_TOKEN" -H "X-Stack-ID: $STACK_ID".

Notes:

• Endpoint-specific headers gcx leaves to you — X-K6TestRun-Id on
  log, trace, and files endpoints (§4, §6, §7) — are still required
  in addition to the auth pair.
• The gcx api flag quirks in §2 (spill envelope, --json field
  filtering, -o for output format) don't apply to curl. Use plain
  curl flags: -o file to save body, --data-binary @file for PUT
  payloads, -w '%{http_code}' for status code, etc.
• Pagination semantics ($orderby, $top, $skip, @nextLink
  from §3) are properties of the v6 endpoints themselves and work
  identically over curl. The @nextLink URL returned by the server
  is already an absolute https://api.k6.io/... URL — pass it back
  to curl unchanged; the plugin-proxy reshape in §3 isn't needed.

---

2. How gcx api paths are shaped

When no subcommand exists, fall back to gcx api against the Grafana
plugin-proxy routes:

• REST API (/cloud/v6/, /cloud/v5/) — prefix with
  /api/plugins/k6-app/resources/cloud/<k6-path>.
• Logs (Loki) — prefix with
  /api/plugins/k6-app/resources/logs/<loki-path>.

k6 path	gcx invocation
/cloud/v6/test_runs/{id}	gcx api /api/plugins/k6-app/resources/cloud/cloud/v6/test_runs/{id}
/cloud/v5/test_runs/{id}/metrics	gcx api /api/plugins/k6-app/resources/cloud/cloud/v5/test_runs/{id}/metrics
Loki /api/v1/query_range?...	gcx api /api/plugins/k6-app/resources/logs/api/v1/query_range?...

Note the doubled cloud/cloud/ in every REST path — the first cloud
is the proxy route, the second is k6's /cloud/v{N}/ namespace.

gcx api flag quirks

gcx api is not a curl clone — a few flags differ from what curl muscle
memory suggests:

• Response body is written to stdout. There is no -o <file> flag
  for saving the body; -o selects output format (json, yaml,
  agents). Use shell redirection (> file) or $(...) capture
  instead.

• Request body uses -d <string>, -d @file, or -d @- (stdin).
  There is no --data-binary; -d @file already preserves bytes.

• Field selection without jq: --json field1,field2,... returns
  only the listed fields, and --json list (or --json '?')
  discovers what's available. Often cleaner than piping into jq for
  shallow extractions.

• Stderr noise: gcx prints a one-line hint: to stderr on most
  invocations. Pipelines into jq should redirect with 2>/dev/null
  to avoid surprises.

• Response headers are not directly exposed by gcx api. When a
  branch in the workflow hinges on Content-Type (e.g. script GET in
  §5), inspect the downloaded body with file <path> instead.

• Large responses spill to a temp file, with stdout reduced to a
  wrapper envelope. The threshold is a few tens of KB, so even
  moderately-sized list endpoints trigger it. The envelope looks like
  this:

  {"spilled_to":"/var/folders/.../gcx-results-<n>.json",
   "bytes":2365037,
   "preview_sample":["@nextLink","value"],
   "message":"Response too large for stdout..."}
  

  Naive json.loads(stdout).get('value', []) patterns silently return
  empty in this case — the envelope has no value key. Two reliable
  fixes:

  • Pass -o json to force inline output regardless of size
    (recommended for scripts that parse the body). The agent-mode
    default formatting is what triggers the spill; -o json opts out.
  • Or detect the envelope and re-read from the spilled file:

    d = json.loads(stdout)
    if 'spilled_to' in d:
        d = json.load(open(d['spilled_to']))
    

  Either works; -o json is fewer lines.

• The Grafana plugin proxy rewrites Content-Type: multipart/...
  to application/json. gcx api itself forwards your
  -H "Content-Type: ..." header correctly (visible in
  --log-http-payload traces), but the upstream plugin proxy
  rewrites multipart Content-Types to JSON before they reach k6's
  API. The net effect: endpoints that require multipart bodies —
  notably POST /cloud/v6/projects/{id}/load_tests for test
  creation, which takes name + script as form parts — return
  HTTP 415 "Unsupported media type \"application/json\"" no
  matter what header you set on the gcx side. Fall back to direct
  curl against api.k6.io (§1.2) for these endpoints —
  curl -F name=... -F script=@... builds the multipart body for
  you and bypasses the plugin proxy. Other Content-Type values
  (e.g. application/octet-stream for the script-update PUT in §5)
  are forwarded through the proxy unchanged.

---

3. Discovering and calling endpoints

gcx k6 subcommands (see gcx help-tree k6) cover the common reads.
For everything else — mutations, niche reads, endpoints not surfaced as
subcommands — the k6 Cloud API surface is large and changes over time.
Rather than rely on a cheat-sheet that goes stale, discover the
operation you need from the OpenAPI spec at request time.

Workflow

1. Fetch the spec once per session (it's large; cache to /tmp):

   gcx api /api/plugins/k6-app/resources/cloud/cloud/v6/openapi > /tmp/k6-openapi.json
   

2. Index by operationId + description first — this keeps the
   working payload small while you search:

   jq '[.paths | to_entries[] | .key as $p | .value | to_entries[]
        | {path: $p, method: .key,
           operationId: .value.operationId,
           description: .value.description}]' /tmp/k6-openapi.json
   

   Grep this for the action you need ("abort", "limits", "schedule", …).

3. Pull the chosen operation's full schema — parameters, request
   body, response — resolving any $ref indirections:

   jq '.paths["<path>"]["<method>"]' /tmp/k6-openapi.json
   # Then for each "$ref": "#/components/schemas/Foo":
   jq '.components.schemas.Foo' /tmp/k6-openapi.json
   

4. Build the gcx api call against the same path, prefixed per §2.
   Authorization is already injected by gcx — do not add it yourself.

List requests

When the operation you're calling is a list endpoint, default to
ordering by created descending (newest first) and paginating
by 20 — both via whatever query parameter names the OpenAPI schema
for that operation exposes. Names vary (ordering=-created,
order_by=created.desc, sort=-created, limit=20, page_size=20),
which is exactly why discovering them from the spec in step 3 matters.
Newest-first means the entries the user usually cares about land in
the first page; a page size of 20 keeps the response small enough to
summarise without burning context.

Full enumeration: paginating with @nextLink

When you need to enumerate all rows (not just the newest page), the
v6 list endpoints cap each response at 1000 rows (the default
$top) and return an @nextLink field pointing at the next page.
gcx k6 runs list --limit 0 does NOT auto-follow @nextLink and
defaults to ascending order — for tests with >1000 historical runs it
silently returns the oldest 1000, not the newest. The
practical effect: (first/last_run) summarised from this output can
be wildly stale (e.g. a daily-scheduled test that's been running for
years will show a last_run from ~3 years ago). Use gcx api
against the v6 endpoint with $orderby=created desc for the
newest-first slice, or loop on @nextLink until it's absent for full
enumeration.

The v6 list endpoints expose OData-style query parameters:

Param	Purpose
$orderby	Ordering — value must be <field> <direction> (e.g. created desc). The allowed fields are operation-specific; created is the common one. Default is ascending.
$top	Page size, default 1000 (also the cap)
$skip	Offset (@nextLink already encodes this for you)
$count	Include total count in response

Two practical defaults for the loop: $orderby=created desc so the
first page contains the newest runs (most of the time the agent only
cares about those), and -o json to opt out of the spill envelope
(see §2) so the parsing is uniform across pages.

import json, subprocess, urllib.parse

CTX = "<stack>"
TEST_ID = "<test_id>"
PROXY = "/api/plugins/k6-app/resources/cloud"

all_runs = []
# Start with newest first; -o json keeps the body inline for clean json.loads().
path = (
    f"{PROXY}/cloud/v6/load_tests/{TEST_ID}/test_runs"
    "?%24orderby=created%20desc&%24top=1000"
)
while path:
    r = subprocess.run(["gcx", "--context", CTX, "api", path, "-o", "json"],
                       capture_output=True, text=True, timeout=60)
    d = json.loads(r.stdout)
    all_runs.extend(d.get("value", []))
    nxt = d.get("@nextLink")
    if not nxt:
        path = None
        continue
    # @nextLink comes back as an absolute http://api.k6.io/... URL with
    # OData params already encoded ($skip, $top, $orderby). Reshape its
    # path+query into the plugin-proxy prefix:
    p = urllib.parse.urlparse(nxt)
    path = f"{PROXY}{p.path}" + (f"?{p.query}" if p.query else "")

Same pattern works for any v6 list endpoint that returns @nextLink,
not just /test_runs. If you only need the few most-recent items,
stop the loop after the first page — with $orderby=created desc that
page is already the newest 1000.

Metrics

Time-series and aggregate metrics live on the v5 API
(/cloud/v5/...) — Prometheus-like query semantics inside OData-style
URL function-calls (query_range_k6(query='...',metric='...')), not
captured by the v6 OpenAPI. The full endpoint reference, selector
syntax, query methods per metric type, and worked examples are inlined
in references/metrics.md — read that before
constructing a metrics query.

Logs

See §4.

---

4. Logs (Loki via gcx api)

The plugin proxies Loki under /api/plugins/k6-app/resources/logs/. The
only header you supply by hand is X-K6TestRun-Id; gcx handles
authorization.

RUN_ID="<run_id>"

# Scope the log window to the run itself: `created` for start, `ended`
# for end. If `ended` is null the run is still in progress — fall back
# to "now". Use a wider hard-coded window only when the run object's
# timestamps don't fit what you're investigating.
RUN=$(gcx api /api/plugins/k6-app/resources/cloud/cloud/v6/test_runs/$RUN_ID 2>/dev/null)
# k6 emits sub-second precision (e.g. "...:58.984041Z"); jq's
# fromdateiso8601 only accepts whole seconds, so strip the fraction.
START=$(echo "$RUN" | jq -r '.created | sub("\\.[0-9]+Z$"; "Z") | fromdateiso8601')
END=$(echo "$RUN"   | jq -r 'if .ended then (.ended | sub("\\.[0-9]+Z$"; "Z") | fromdateiso8601) else (now | floor) end')

QUERY=$(printf '{test_run_id="%s"}' "$RUN_ID" | jq -sRr @uri)

# Save the raw response to /tmp/ — log payloads can be large; streaming
# them inline burns context. Summarise from the file, then jq into
# specific entries only when needed.
gcx api "/api/plugins/k6-app/resources/logs/api/v1/query_range?query=${QUERY}&direction=backward&start=${START}&end=${END}&limit=1000" \
  -H "X-K6TestRun-Id: $RUN_ID" 2>/dev/null > /tmp/run_${RUN_ID}_logs.json

# Tight summary — counts and stream labels only:
jq '{status, streams: (.data.result | length),
     total_entries: ([.data.result[].values | length] | add),
     stream_labels: [.data.result[].stream]}' /tmp/run_${RUN_ID}_logs.json

Pull individual entries from /tmp/run_${RUN_ID}_logs.json as needed
(e.g. jq '.data.result[].values[]' …) rather than re-running the
query.

Every LogQL query must include the {test_run_id="<run_id>"} stream
selector — the plugin proxy partitions logs by run and rejects (or
returns nothing for) queries without it. Layer additional filters on
top of that selector:

• {test_run_id="<run_id>"} — everything
• {test_run_id="<run_id>"} | level=~"(error|warn)" — errors and warnings only
• {test_run_id="<run_id>"} |= "specific text" — substring filter

Direction & window tips:

• Scope start/end to the run's created/ended fields, not to
  wall-clock "last hour" — otherwise queries silently miss anything
  older than the window. The only reason to deviate is when you
  specifically want a different interval (e.g. surrounding context).
• direction=forward with start = run.created to find the first errors.
• direction=backward with end = run.ended (or now, if still running)
  to find the most recent output.
• Loki retention typically outlives k6's cascade-delete, so logs of a
  deleted child run may still be queryable for a while.

---

5. Editing a test script safely

Two distinct script endpoints

There are two GET endpoints that return a k6 script body, and they are
not interchangeable:

Endpoint	What it returns	When to use
/cloud/v6/load_tests/<test_id>/script	The current load-test script (mutable; supports PUT)	Editing the script; reading current state
/cloud/v6/test_runs/<run_id>/script	The script snapshot bundled into a specific run (read-only)	Investigating what a past run actually executed; diffing across versions

The two can drift apart: if the load-test script is edited after a
run completes, that run's bundled snapshot stays frozen at what it
executed, while the load-test endpoint serves the new current version.
The bundled-snapshot endpoint is GET-only — you cannot mutate
historical bytes.

The safe-edit recipe below uses the load-test endpoint (the editable
one). For run-vs-run script diffs (e.g. "did the script change between
the last passing and first failing run?"), GET both runs'
/test_runs/<id>/script and diff them locally.

Script body format

The script GET endpoint returns one of two shapes — always detect which
before assuming the format:

• Single js/ts file. The recipe below handles this case directly.

• k6 tar archive (plain tar or gzipped). A multi-file project
  bundle (entry script + imported modules + assets). To edit: extract
  the JS file, modify it, then use k6 archive to rebuild the
  archive from the modified JS. Do not manually repack with
  tar — the archive contains a metadata.json with parsed options
  (projectID, thresholds, scenarios) that k6 archive regenerates
  correctly from the script source. Manual repacking preserves stale
  metadata and causes runtime errors (e.g. projectID mismatch).

  # Edit a k6 tar archive
  tar -xf /tmp/script_body -C /tmp/extracted/   # extract
  # ... edit the JS file ...
  k6 archive /tmp/edited_script.js -O /tmp/new_archive.tar  # rebuild
  

gcx api doesn't expose response headers (see §2), so detect the shape
by inspecting the downloaded body with file(1):

gcx api /api/plugins/k6-app/resources/cloud/cloud/v6/load_tests/$ID/script \
  > /tmp/script_body
file /tmp/script_body
# Expected output (examples):
#   ASCII text          → js/ts source
#   POSIX tar archive   → k6 tar bundle
#   gzip compressed data → gzipped tar bundle

The PUT body must be the raw script (or archive) bytes
(application/octet-stream). gcx forwards the request to k6 unchanged.

ID="<load_test_id>"

# 1. Pull current script (single-file js/ts case)
gcx api /api/plugins/k6-app/resources/cloud/cloud/v6/load_tests/$ID/script \
  > /tmp/script_current.js

# 2. Backup
cp /tmp/script_current.js /tmp/script_backup_$(date +%s).js

# 3. Edit → /tmp/script_new.js

# 4. Local parse-only sanity check
k6 inspect /tmp/script_new.js | head -20

# 5. 1-iteration smoke (edit IN-FILE; --iterations CLI flag breaks browser scenarios)
sed 's/iterations: [0-9]\+/iterations: 1/' /tmp/script_new.js > /tmp/script_1iter.js
k6 run --quiet /tmp/script_1iter.js   # exit 0 = pass, 99 = threshold fail

# 6. PUT — Content-Type must be application/octet-stream
gcx api /api/plugins/k6-app/resources/cloud/cloud/v6/load_tests/$ID/script \
  -X PUT \
  -H "Content-Type: application/octet-stream" \
  -d "@/tmp/script_new.js"

# 7. Verify by re-fetching and comparing sha256 — the two hashes MUST match.
#    Do not rely on the `updated` timestamp; it does not bump on script PUT.
gcx api /api/plugins/k6-app/resources/cloud/cloud/v6/load_tests/$ID/script \
  > /tmp/script_verify.js
shasum -a 256 /tmp/script_new.js /tmp/script_verify.js

If the PUT returns 415, double-check that -H "Content-Type: application/octet-stream" made it through (some shell quoting mistakes
can drop it). Pass -vvv to gcx api for the request/response trace
when debugging.

---

6. Browser screenshots

Browser-module runs write screenshot PNGs to per-run S3 storage —
that's the only artifact type the files API surfaces today. They're
not exposed via /cloud/v6/; retrieval goes through a separate
cloud-resources/v1/files/ plugin route in a two-step flow. Both
calls require the same X-K6TestRun-Id header used for log queries
(§4) — gcx still handles auth, but the run ID must be supplied by
hand or the endpoint rejects with HTTP 422.

RUN_ID="<run_id>"

# 1. Index — JSON array of screenshot paths owned by this run. Empty
#    array if the run took none (e.g. non-browser tests, or browser
#    runs that didn't call page.screenshot()).
gcx api /api/plugins/k6-app/resources/cloud/cloud-resources/v1/files/index \
  -H "X-K6TestRun-Id: $RUN_ID" -o json 2>/dev/null > /tmp/files_${RUN_ID}.json

# Each entry looks like:
#   "7542817/files/screenshots/screenshots/login-success.png"
# The doubled "screenshots/screenshots/" segment is real, not a typo —
# pass the path back unchanged to step 2.

# 2. Request pre-signed download URLs for the files you want. The
#    request body must be JSON; Content-Type matters.
FILES=$(jq -c '[.[] | {name: .}]' /tmp/files_${RUN_ID}.json)
PAYLOAD=$(jq -nc --argjson files "$FILES" \
  '{service:"aws_s3", operation:"download", files:$files}')

gcx api /api/plugins/k6-app/resources/cloud/cloud-resources/v1/files/generate-pre-signed-url \
  -X POST \
  -H "X-K6TestRun-Id: $RUN_ID" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD" -o json 2>/dev/null > /tmp/presigned_${RUN_ID}.json

# 3. Download each pre-signed URL directly — they're plain S3 GETs, no
#    gcx and no auth header (the signature is in the URL). The URLs
#    are valid for 24h (X-Amz-Expires=86400); re-run step 2 if they
#    expire.
mkdir -p /tmp/run_${RUN_ID}_files
jq -r '.urls[] | [.name, .pre_signed_url] | @tsv' /tmp/presigned_${RUN_ID}.json |
  while IFS=$'\t' read -r NAME URL; do
    curl -sS -o "/tmp/run_${RUN_ID}_files/$(basename "$NAME")" "$URL"
  done

Notes worth knowing

• Index before signing. generate-pre-signed-url does not
  validate that the file exists — it will happily mint a URL for any
  key, and the 404 only surfaces when you try to download (S3 returns
  <Error><Code>NoSuchKey</Code>...). Always derive the file list
  from files/index, not from a guess at the path shape.
• Batch the sign request. files is an array, so request all the
  URLs you need in one POST rather than one call per file — same
  24h expiry covers the whole batch.
• Browser tests vs. protocol tests. Only runs that called
  page.screenshot() have entries in the index; a pure protocol/HTTP
  run will return []. Don't assume the index is non-empty.

---

7. Browser traces (Tempo via gcx api)

Browser-module runs emit OTel spans for every iteration, navigation,
locator click, screenshot, web-vital observation, etc. The plugin
proxies a Tempo backend under /api/plugins/k6-app/resources/logs/
(same prefix as Loki — see §4), and the same X-K6TestRun-Id header
is required on every call. Without it, both search and fetch return
HTTP 401 "Test run ID missing".

Retrieval is a two-step flow: TraceQL search → fetch full trace by
ID. The full trace is large (≈100 KB on disk for a 120-span iteration
because -o json pretty-prints; ~50 KB compact), so the
join+summarise step is what keeps agent context lean.

RUN_ID="<run_id>"

# 1. Find the run's start/end window and pick the scenario name.
#    Same caveat as §4: strip the sub-second fraction before
#    fromdateiso8601, and fall back to "now" if the run is still
#    running. Add a small buffer because spans can land slightly
#    after the run object reports `ended`.
RUN=$(gcx api /api/plugins/k6-app/resources/cloud/cloud/v6/test_runs/$RUN_ID 2>/dev/null)
START=$(echo "$RUN" | jq -r '.created | sub("\\.[0-9]+Z$"; "Z") | fromdateiso8601')
END=$(  echo "$RUN" | jq -r 'if .ended then (.ended | sub("\\.[0-9]+Z$"; "Z") | fromdateiso8601) else (now|floor) end')
START=$((START - 60))
END=$((END + 60))

SCENARIO="ui"  # whatever your scenario is named; check run.ui.exec / k6 script

# 2. Search for iteration root spans. TraceQL goes in `q`; URL-encode
#    it. `start`/`end` must be unix seconds — RFC3339 returns
#    HTTP 400 `invalid start: strconv.ParseUint`. limit=500 caps the
#    result, enough to cover several thousand iterations.
Q=$(printf '{ name = "iteration" && span.test.iteration.number >= 0 && span.test.vu >= 0 && span.test.scenario = "%s" }' "$SCENARIO")
QE=$(printf '%s' "$Q" | jq -sRr @uri)

gcx api "/api/plugins/k6-app/resources/logs/api/v1/tempo/api/search?start=${START}&end=${END}&q=${QE}&limit=500" \
  -H "X-K6TestRun-Id: $RUN_ID" -o json 2>/dev/null > /tmp/traces_${RUN_ID}.json

# Each entry has: traceID (32-char hex), rootServiceName ("k6"),
# rootTraceName ("iteration"), durationMs, startTimeUnixNano, and a
# spanSet preview of the iteration root span's attributes
# (test.iteration.number, test.vu, test.scenario).

# 3. Fetch a full trace. The response is OTLP-shaped:
#    { "batches": [ { "resource": {...}, "scopeSpans": [ { "spans": [...] } ] } ] }
TRACE_ID=$(jq -r '.traces[0].traceID' /tmp/traces_${RUN_ID}.json)
gcx api "/api/plugins/k6-app/resources/logs/api/v1/tempo/api/traces/$TRACE_ID" \
  -H "X-K6TestRun-Id: $RUN_ID" -o json 2>/dev/null > /tmp/trace_${TRACE_ID}.json

Compact summary for an agent

The OTLP body for a single iteration can run ~100 KB pretty-printed.
Dumping it verbatim into context is wasteful — most of the useful
signal lives in the span-name distribution, the slowest individual
spans, and the web-vital ratings. The pipeline below collapses a
trace into ~1–2 KB of plain text:

jq -r '
  # OTel value envelope: pick by key presence, not //-chaining — jq's //
  # treats `false` as missing and would drop legitimate boolValue:false.
  def attrval:
    if   has("stringValue") then .stringValue
    elif has("intValue")    then .intValue
    elif has("boolValue")   then .boolValue
    elif has("doubleValue") then .doubleValue
    else null end;
  def attrs: [.attributes[] | {(.key): (.value | attrval)}] | add // {};
  def dur:   (((.endTimeUnixNano|tonumber) - (.startTimeUnixNano|tonumber)) / 1000000 | floor);

  [.batches[].scopeSpans[].spans[] | {name, dur: dur, a: attrs, status: (.status.code // "OK")}] as $spans

  | "── span-name rollup (count · total ms · max ms) ──",
    ([$spans[] | {name, dur}]
       | group_by(.name) | map({name: .[0].name, n: length,
                                t: (map(.dur)|add), m: (map(.dur)|max)})
       | sort_by(-.t)[]
       | "  \(.n|tostring|.+"      "|.[0:4])  \(.t|tostring|.+"        "|.[0:7])  \(.m|tostring|.+"      "|.[0:6])  \(.name)"),

    "\n── slowest spans (ms · name · navigation.url / page.goto.url) ──",
    ([$spans[] | select(.name != "iteration")] | sort_by(-.dur) | .[0:8][]
       | "  \(.dur|tostring|.+"        "|.[0:7])  \(.name)\(if .a["navigation.url"] // .a["page.goto.url"] then "  " + (.a["navigation.url"] // .a["page.goto.url"]) else "" end)"),

    "\n── web-vital ratings ──",
    ([$spans[] | select(.name == "web_vital")
       | {n: .a["web_vital.name"], v: .a["web_vital.value"], r: .a["web_vital.rating"]}]
       | group_by(.n) | map({name: .[0].n,
                             ratings: ([.[].r] | group_by(.) | map({(.[0]): length}) | add)})[]
       | "  \(.name)  \(.ratings)"),

    "\n── span errors ──",
    ([$spans[] | select(.status != "OK" and .status != null)] | length | "  count: \(.)")
' /tmp/trace_${TRACE_ID}.json

On a run like 7542817 the output is something like:

── span-name rollup (count · total ms · max ms) ──
  1     154552   154552  iteration
  37    153391   17746   navigation
  11    21778    5168    page.waitForNavigation
  ...

── slowest spans (ms · name · navigation.url / page.goto.url) ──
  17746    navigation  https://k6e2etests.grafana-dev.net/a/k6-app/projects
  14992    navigation  https://k6e2etests.grafana-dev.net/a/k6-app/projects/58195
  ...

── web-vital ratings ──
  LCP   {"poor":5,"needs-improvement":1}
  CLS   {"good":2}
  ...

Two paragraphs of text capture which navigations are slow, which
web vitals are regressing, and the overall span-name distribution
— enough to reason about browser performance without paging through
the OTLP tree.

Notes worth knowing

• Header is mandatory. Both /search and /traces/<id> return
  HTTP 401 without X-K6TestRun-Id. The header scopes the query to
  the run's tenant.
• start/end are unix seconds. RFC3339 ISO strings get
  HTTP 400 invalid start: strconv.ParseUint. They're technically
  optional — search works without them — but providing a window
  matching the run's created/ended (plus ~60s buffer) keeps the
  query fast and avoids matching unrelated runs that share the
  scenario name.
• TraceQL, not LogQL. The q parameter uses TraceQL — span
  predicates are written as span.<attribute> and combined with
  &&. The suggested query filters iteration root spans for a
  specific scenario; broaden by dropping test.scenario, narrow by
  adding e.g. span.test.vu = 3 && span.test.iteration.number = 5
  to pinpoint a single iteration on a single VU.
• Scenario names come from the run. They're the keys of
  .options.scenarios on the run object —
  gcx api /api/plugins/k6-app/resources/cloud/cloud/v6/test_runs/$RUN_ID --json options 2>/dev/null | jq -r '.options.scenarios | keys[]'
  lists them. The default scenario is named default; browser tests
  often name it ui, browser, etc.
• Span IDs in the OTLP body are base64. The traceID in the
  search response is hex (the form /traces/<id> accepts); the
  inner traceId/spanId/parentSpanId fields inside the OTLP
  batch are base64-encoded bytes. Cross-correlate parent/child via
  parentSpanId == spanId, both in base64 — no need to decode.
• Useful attribute keys on browser-test spans: navigation.url,
  page.goto.url, screenshot.path, web_vital.name,
  web_vital.value, web_vital.rating, test.scenario, test.vu,
  test.iteration.number, k6.test_run_id. These are the ones
  worth surfacing in summaries; the OTel value envelope is
  {stringValue|intValue|boolValue|doubleValue} (the jq
  attrval helper above handles all four).

---

8. Cloud Insights (audit results for a run)

Cloud Insights runs heuristics against a finished test — checks for
high cardinality, web-vital regressions, missing thresholds,
overutilised load generators, and so on — and exposes the results
through a separate /resources/insights/ plugin route (not
/cloud/v{N}/). gcx still handles auth; no extra header is needed.

Three calls produce the data, and the agent-useful output is a join
across two of them:

RUN_ID="<run_id>"
BASE="/api/plugins/k6-app/resources/insights/insights/api/v1/testrun/$RUN_ID"

# 1. List executions for the run, take the most recent. The response
#    is { "executions": [ {id, version}, ... ] } — NOT a bare array.
#    Pick the last entry; insights re-runs append, and the newest one
#    reflects the current set of audits/scores.
EXEC_ID=$(gcx api "$BASE/executions" -o json 2>/dev/null \
  | jq -r '.executions[-1].id')

# 2. Audit definitions (id, title, description, weight). ~15 items.
gcx api "$BASE/executions/$EXEC_ID/audits" -o json 2>/dev/null \
  > /tmp/insights_audits_${RUN_ID}.json

# 3. Audit results (audit_id, status, score, explanation, actions).
gcx api "$BASE/executions/$EXEC_ID/audits/results" -o json 2>/dev/null \
  > /tmp/insights_results_${RUN_ID}.json

Both responses use the same top-level key — audits — but the
contents differ: step 2 is the catalog of what each audit checks,
step 3 is what that audit found on this particular run. Cross-join
them via result.audit_id == audit.id (1:1 in practice).

Joining into a compact, agent-readable summary

The raw audit + results JSON together is ~10 KB. Dumping both into
context just to read out three lines per audit is wasteful — do the
join in jq and emit a single tight block. The pipeline below is
the recommended shape:

jq -nr \
  --slurpfile a /tmp/insights_audits_${RUN_ID}.json \
  --slurpfile r /tmp/insights_results_${RUN_ID}.json '
  ($a[0].audits | INDEX(.id)) as $defs
  | $r[0].audits
  | map({
      title:         ($defs[.audit_id].title // "?"),
      description:   ($defs[.audit_id].description // ""),
      status:        .status,
      status_reason: .status_reason,
      score: (
        if .score == null            then "n/a"
        elif .score.type == "binary" then (if .score.value then "pass" else "fail" end)
        else (.score.value | tostring)
        end),
      explanation: (.explanation // "" | gsub("\n+"; " ") | .[0:300]),
      actions:     (.actions // [])
    })
  | .[]
  | "── \(.title) — score: \(.score)\(if .status == "failed" then " [audit did not run: \(.status_reason // "unknown")]" else "" end)\n  \(.description)\n  → \(.explanation)\(if (.actions|length) > 0 then "\n  actions:\n    - " + (.actions|join("\n    - ")) else "" end)\n"
'

For a 15-audit run this emits ~5 KB of plain text — title, score,
one-line description, one-line explanation, and any action items.
That's enough for the agent to reason about the test's health
without re-reading either JSON blob.

Notes worth knowing

• status ≠ verdict. status: "succeeded" means the audit
  executed. The verdict lives in score (binary true/false, or
  numeric 0…1 where 1 is best). status: "failed" means the audit
  itself could not run (typically status_reason: "missing data" —
  e.g. the HTTP Spans audit on a non-tracing test); the score field
  is absent. Treat these as "no signal", not as failures.
• Score thresholds vary per audit. A numeric 0.94 might be
  fine for one audit and concerning for another — there's no global
  cutoff. The explanation is authoritative for what the score
  means; surface it verbatim rather than inventing a pass/fail rule.
• actions is the actionable bit. Only present when the audit
  has concrete recommendations (e.g. "Reduce the cardinality of the
  url label …"). When summarising a run for a user who's trying to
  improve it, lead with audits that have a non-empty actions array.
• Pick the last execution, not the first. .executions[] is in
  chronological order; re-runs append. Older executions reflect
  older audit logic and may have stale results.
• Insights is a post-run analysis. If the run hasn't finished
  (or never produced enough data for insights to compute), the
  executions list may be empty — bail out gracefully on
  length == 0.

---

9. Local k6 CLI (smoke tests and k6 cloud run)

The local k6 CLI is the right tool for parse checks and 1-iteration
smoke runs before pushing to cloud:

k6 inspect script.js | head -20      # parse-only sanity
k6 run --quiet script.js             # run locally

For k6 cloud run (uploads + runs in cloud from your laptop), authenticate
k6 cloud login with the token and stack URL pulled from gcx — token
comes from gcx k6 auth token, stack URL from the active gcx context's
grafana.server field:

TOKEN=$(gcx --context <ctx> k6 auth token)
STACK=$(gcx --context <ctx> config view --minify -o json | jq -r '.contexts[].grafana.server')
k6 cloud login --token "$TOKEN" --stack "$STACK"
k6 cloud run script.js

k6's cloud config (~/.config/k6/cloud.json) is single-context, so
re-run k6 cloud login whenever you switch gcx contexts — otherwise
k6 cloud run will keep targeting the previous stack.

Exit codes: 0 pass, 99 threshold fail, anything else = script/runtime error.

---

10. Gotchas

Symptom	Cause	Fix
401 "Invalid or expired token — run gcx login to refresh"	gcx OAuth session expired	gcx login --context <ctx>
403 / 404 on a path that looks right	Forgot the doubled cloud/cloud/ for a REST endpoint	Use …/resources/cloud/cloud/v{N}/…
415 unsupported media type on script PUT	Missing -H "Content-Type: application/octet-stream"	Add it; pass -vvv (or --log-http-payload) to gcx api to inspect the request
Script PUT returns 200 but doesn't take effect	updated timestamp does not bump on script change	Verify by sha256 of GET (§5 step 7)
Run status passed but checks failed	Zero-observation thresholds report as pass; check() alone never fails a run	Add 'checks{check:<name>}': ['rate==1.0']; in catch blocks, check(null, {"script completed":()=>false}) to force an observation
Loki query returns nothing for a recent run	X-K6TestRun-Id header missing	Always pass -H "X-K6TestRun-Id: <run_id>" on log queries
gcx k6 runs list --limit 0 returns the oldest 1000 rows, not the newest	Subcommand doesn't follow @nextLink and defaults to ascending order — for >1000 runs the first/last you see are the start of the history, not the recent activity	Use gcx api with $orderby=created desc for a newest-first slice, or the full @nextLink loop in §3
gcx k6 load-tests update -f returns ✔ Updated but the change doesn't take effect	Fields outside the v6 PATCH schema (PatchLoadTestApiModel allows only name, baseline_test_run_id — additionalProperties: false) are silently dropped. Notably project_id is NOT updatable this way	For project moves use the dedicated /move endpoint (§11); for other mutations cross-check the PATCH schema in the OpenAPI spec. Always re-GET to confirm
gcx k6 load-tests list --project-id <id> returns tests from all projects	The flag is accepted but never filters — /cloud/v6/load_tests has no project query param	Use GET /cloud/v6/projects/{id}/load_tests via gcx api, or filter client-side with select(.project_id == X) in jq
HTTP 415 "Unsupported media type \"application/json\"" on a multipart POST through gcx api	The Grafana plugin proxy rewrites multipart Content-Types to application/json before forwarding (gcx itself sends the header you set; the proxy strips it)	Fall back to direct curl against api.k6.io (§1.2). Affects test creation (POST /cloud/v6/projects/{id}/load_tests) and any other multipart endpoint
401 Unauthorized calling api.k6.io / cloudlogs.k6.io directly (curl mode)	Missing/wrong Authorization: Bearer … or X-Stack-ID header	Re-check both headers; resolve X-Stack-ID from a stack URL via /cloud/v6/auth (§1.2)
404 calling api.k6.io/api/plugins/... (curl mode)	Left the plugin-proxy prefix in by mistake	Strip /api/plugins/k6-app/resources/{cloud,logs,insights} — see §1.2

---

11. Mutations not covered by update -f

gcx k6 <resource> update -f follows the v6 PATCH schema for that
resource. Fields outside the schema are silently dropped while gcx
still prints ✔ Updated <resource> <id> — see the §10 row. Several
common mutations have dedicated endpoints instead, and the PATCH
route will no-op on them.

Mutation	Endpoint	Body
Move test to another project	PUT /cloud/v6/load_tests/{id}/move	{"project_id": <int>}
Start a test run	POST /cloud/v6/load_tests/{id}/start	{} (or run options)

Polling a started run: After starting a run, poll
GET /cloud/v6/test_runs/{id} until status reaches completed or
aborted. Always check the result field alongside status —
status: completed with result: error means a configuration or
infrastructure failure (not a threshold breach). On any non-passed
result, immediately fetch logs (§4) to surface the error rather than
waiting for the user to report it.

| Abort a running test | POST /cloud/v6/test_runs/{id}/abort | empty |
| Set / overwrite a schedule | POST /cloud/v6/load_tests/{id}/schedule | Schedule body (recurrence_rule or cron) |
| Deactivate / reactivate a schedule | POST /cloud/v6/schedules/{id}/{deactivate,activate} | empty |
| Create a load test (multipart!) | POST /cloud/v6/projects/{id}/load_tests | multipart: name + script |
| Persist a run past retention | POST /cloud/v6/test_runs/{id}/save | empty (paired with /unsave) |

The PATCH-style updates that do work via update -f:

Resource	Updatable fields
load test	name, baseline_test_run_id (per PatchLoadTestApiModel)
project	name only (per PatchProjectApiModel)

Both schemas declare additionalProperties: false — any other field
you put in the manifest is silently filtered out before the PATCH is
sent, even though gcx still reports ✔ Updated. Don't try to flip
is_default or move a grafana_folder_uid through update -f;
they're not exposed for mutation on the v6 PATCH.

Cross-check by reading the operation's request schema in the OpenAPI
spec (workflow in §3) before assuming a field is mutable.

Worked example — move a test between projects

gcx api /api/plugins/k6-app/resources/cloud/cloud/v6/load_tests/<test_id>/move \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{"project_id": <new_project_id>}'

# Verify — re-GET and check project_id reflects the new value.
# Do not trust the absence of an error from the PUT; HTTP 204 with
# empty body is the success shape but gcx api prints nothing.
gcx --context <ctx> k6 load-tests get <test_id> -o json | jq '{id, name, project_id}'

The OpenAPI description for this endpoint is explicit: "Move a load
test to a different project of the same organization. All respective
test runs will be also moved to the new project." You don't need to
migrate runs separately.

Cascade behavior worth knowing

• Deleting a load test cascade-deletes its schedule. The schedule
  is gone from /cloud/v6/schedules and /cloud/v6/load_tests/{id}/schedule
  immediately. No need to gcx k6 schedules delete <load-test-id>
  first as a defensive step.
• Deleting a project with a running test fails with HTTP 409
  ("Cannot delete project with a running test." per the OpenAPI
  spec). Non-running tests appear to be removed with the project,
  but if you want to inventory a project's contents before deleting
  it, use GET /cloud/v6/projects/{id}/load_tests (NOT
  gcx k6 load-tests list --project-id <id>, which doesn't filter —
  see §10).
• Moving a test moves its runs and run history with it. Schedule
  attachment also follows the test (it's keyed by load_test_id,
  not by project).

Verification rule of thumb

The recurring pattern in this skill is "gcx confirms success even
when the underlying call no-ops". Whenever you mutate state:

1. Note what you expected to change (field, count, status).
2. Re-GET the resource and confirm the change is reflected.
3. If it isn't, check whether the mutation needed a dedicated
   endpoint (this section) rather than update -f.