For the complete documentation index, see llms.txt. This page is also available as Markdown.

Akamai-BM-Telemetry Header

How to handle sites that protect their API with an Akamai-BM-Telemetry request header instead of a sensor_data post, using the Hyper Solutions telemetry endpoints and SDKs.

Some sites protect their API host with an Akamai-BM-Telemetry request header instead of a sensor_data post. The page loads the usual Akamai script, but instead of posting sensor data, the script attaches a freshly built header to every protected XHR/fetch call. The protected host rejects calls without a valid header.

Recognising it

  • The site's protected API calls carry a header like:

    Akamai-BM-Telemetry: a=74CA869260DD6EF307EA308F541F4DF5&&&e=E7C2...~3421233~3491378&&&sensor_data=MzsxOzI7...&&&j=AAQAAAAG%2f%2f...
  • There is no sensor_data POST to the script URL.

  • The page makes a GET /_bm/get_params?type=web-jsto&v=... request once, and its JSON response holds a j value.

  • The protected host answers 403 when the header is missing or invalid, often while page loads and other requests succeed.

The header has up to four fields, joined by &&&:

Field
Meaning

a

The _abck id, taken from the _abck cookie when its second field is -1; empty otherwise.

e

The raw bm_sz cookie.

sensor_data

The base64 sensor payload.

j

The j from the page's get_params response, verbatim (still URL-encoded). Absent when the site has none.

You do not need to build any of this yourself: POST /v1/telemetry returns the complete header value.

Flow

Step 1: Load the page and fetch the script

Load the page and parse and fetch the Akamai script exactly as in the sensor flow (steps 1 to 3). After the page load you hold the _abck and bm_sz cookies, the script content and the script URL.

Use the cookies the page itself holds. When the protected calls go to another host without credentials (as on Paylogic), the browser sends no cookies there and ignores the Set-Cookie headers those responses carry, so _abck and bm_sz stay the page-load values.

Step 2: Get the get_params path

Call POST /v1/telemetry/params with the page URL and the script (or its sha256 as scriptHash). It returns:

  • payload: the get_params path, exactly as the browser requests it, for example /_bm/get_params?type=web-jsto&v=aNjc97OfvDBoc9gY88Sbui9EwsB6tx66vij5EVYP8U0=. The tag is not URL-encoded: send the path as returned, +, / and = included.

  • context: a context you can send on the first telemetry call instead of the script.

/v1/telemetry/params does not count towards your usage.

Step 3: Request get_params once

GET the path on the page's origin, with the page's cookies, like the browser does (sec-fetch-site: same-origin, sec-fetch-mode: cors). The response is JSON:

Keep j verbatim, still URL-encoded. Request get_params once per session, not before every call.

Step 4: One telemetry header per protected call

Before every protected request, call POST /v1/telemetry with the sensor fields, j, and the context from the previous call (on the first call, the context from step 2, or the script and no context). Send the returned payload verbatim as the Akamai-BM-Telemetry header, and keep the returned context for the next call.

Code samples

hyper-sdk-playwright's AkamaiHandler handles this automatically from 1.0.0-beta.16: it replaces the Akamai-BM-Telemetry header on every request that carries one with an API-generated header, chained across calls. Nothing to configure.

These are the minimum SDK versions with the telemetry methods:

SDK
Minimum version
Methods

Go, github.com/Hyper-Solutions/hyper-sdk-go/v4

v4.0.0

GenerateTelemetry, GetTelemetryParams

Python, hyper-sdk

4.0.0

generate_telemetry, get_telemetry_params

JS / TS, hyper-sdk-js

5.0.0

generateTelemetry, getTelemetryParams

hyper-sdk-playwright

1.0.0-beta.16

automatic

Troubleshooting

  • 403 on the first protected call: check that scriptUrl is the full URL of the Akamai script (the one in the page's script tag), and that abck and bm_sz are the page-load cookies.

  • The first calls pass, later ones fail: you are reusing a header or a context. Every call takes a fresh header, and every telemetry request sends the context from the previous response.

  • j looks double-encoded: send it exactly as get_params returned it, without decoding or re-encoding.

  • Send the protected request's other headers the way the site's own app does, including any client hints the site asks for.

Last updated