gcx

• 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.

command -v gcx

• 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.

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}

   :
   bash

   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".)

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 ...

-H ...

-H "Authorization: Bearer $K6_TOKEN" -H "X-Stack-ID: $STACK_ID"

• 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.

gcx api

• 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>

  .

/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

/api/v1/query_range?...

gcx api /api/plugins/k6-app/resources/logs/api/v1/query_range?...

cloud/cloud/

cloud

/cloud/v{N}/

gcx api

• 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:
  json

  {"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:
    python

    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.

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

   /tmp

   ):
   bash

   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:
   bash

   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:
   bash

   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.

• 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).
  bash

  # 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

file(1)

gcx api /api/plugins/k6-app/resources/cloud/cloud/v6/load_tests/$ID/script \
  > /tmp/script_body
file /tmp/script_body

/tmp/script_current.js

/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.

---

• 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.

• 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).

/tmp/insights_audits_${RUN_ID}.json

/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).

• 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

  .

• 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).

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

   .