Network inspection

Mobilerun can inspect a device’s network traffic and stream decoded HTTP/1.1, HTTP/2, HTTP/3, and application WebSocket events to your local machine. The stream is live-only and does not require adb or direct access to the device. Unlike the ADB and Frida tunnels, network inspection is session-based. You start a session with the REST API, connect to the returned WebSocket with either your API key or the device’s existing stream token, and stop the session when you are finished.

Requirements

Network inspection must be enabled for the device’s hosting pool. Contact Mobilerun support at contact@mobilerun.ai if you need access.

A Mobilerun API key (dr_sk_...)
curl, jq, and websocat installed locally

Set the API key and device ID in your shell:

export MOBILERUN_API_KEY='dr_sk_...'
export DEVICE_ID='YOUR_DEVICE_ID'
export MOBILERUN_API='https://api.mobilerun.ai/v1'

Check whether the device supports network inspection:

curl --fail-with-body -sS \
  -H "Authorization: Bearer $MOBILERUN_API_KEY" \
  "$MOBILERUN_API/devices/$DEVICE_ID/capabilities" \
  | jq '.capabilities.trafficInspection'

The value must be true. The capability is granted when a device is placed in an enabled pool. Disabling inspection for that pool also prevents new sessions and stops active sessions.

Endpoints

Method	Endpoint	Purpose
`POST`	`/v1/devices/{deviceId}/traffic/sessions`	Start a session and receive stream credentials.
`GET`	`/v1/devices/{deviceId}/traffic/sessions`	List recent session metadata.
`GET`	`/v1/devices/{deviceId}/traffic/sessions/{sessionId}`	Read status and return the device stream credentials for a live session.
`DELETE`	`/v1/devices/{deviceId}/traffic/sessions/{sessionId}`	Stop a session and restore device networking.
`WSS`	Returned as `stream.url`	Receive live decoded traffic events.

Use your Mobilerun API key for the REST endpoints. Non-browser WebSocket clients also authenticate with that API key. Browser clients, which cannot set an Authorization header on WebSocket, use the existing device stream token returned in stream.token as a token query parameter. Always start with the returned stream.url instead of constructing the path yourself.

Start an inspection session

Create a session with a unique Idempotency-Key so retrying the same request does not start another session:

export REQUEST_ID="traffic-$(date +%s)-$$"

SESSION="$(
  curl --fail-with-body -sS -X POST \
    -H "Authorization: Bearer $MOBILERUN_API_KEY" \
    -H "Idempotency-Key: $REQUEST_ID" \
    -H 'Content-Type: application/json' \
    -d '{}' \
    "$MOBILERUN_API/devices/$DEVICE_ID/traffic/sessions"
)"

export SESSION_ID="$(jq -er '.id' <<<"$SESSION")"
jq '{id, state, expiresAt, retention}' <<<"$SESSION"

Only one session can be starting, active, or stopping for a device at a time. Starting another returns 409 TRAFFIC_ALREADY_ACTIVE.

Wait until the session is active

Starting inspection is asynchronous. Poll the status endpoint until the device producer is ready:

while true; do
  STATUS="$(
    curl --fail-with-body -sS \
      -H "Authorization: Bearer $MOBILERUN_API_KEY" \
      "$MOBILERUN_API/devices/$DEVICE_ID/traffic/sessions/$SESSION_ID"
  )"

  STATE="$(jq -er '.state' <<<"$STATUS")"
  [ "$STATE" = 'active' ] && break

  if [ "$STATE" != 'starting' ]; then
    jq . <<<"$STATUS"
    exit 1
  fi

  sleep 1
done

export STREAM_URL="$(jq -er '.stream.url' <<<"$STATUS")"
export STREAM_PROTOCOL="$(jq -er '.stream.protocol' <<<"$STATUS")"

While the session is starting or active, the status response returns the device’s existing stream token. This is the same device-bound credential used by other device WebSocket endpoints; it is not a traffic-specific or session-scoped viewer token. It is revoked when the device is terminated and rotates when device ownership changes. Treat it as a secret and do not log URLs containing it.

Stream events with websocat

Open the returned WebSocket URL with your Mobilerun API key and the required subprotocol:

websocat --no-async-stdio -B 8388608 \
  -H="Authorization: Bearer $MOBILERUN_API_KEY" \
  -H="Sec-WebSocket-Protocol: $STREAM_PROTOCOL" \
  "$STREAM_URL" \
  | jq --unbuffered -c .

Do not send stream.token as a Bearer token. For non-browser clients, the Bearer credential is your dr_sk_... API key. The websocat options keep large JSON events intact when piping them into jq, including on macOS.

Browser WebSocket clients

The browser WebSocket API cannot set an Authorization header. Add the returned device stream token to the returned URL instead:

const streamUrl = new URL(session.stream.url);
streamUrl.searchParams.set('token', session.stream.token);

const socket = new WebSocket(streamUrl, session.stream.protocol);
socket.onmessage = ({ data }) => console.log(JSON.parse(data));

The edge authenticates the query token against the device before forwarding the WebSocket upgrade. Devices API then verifies that the traffic session belongs to the same device owner and is still starting or active. Exercise the app on the device while this command is running. Each line is a JSON event. The first event is hello; subsequent event types are:

Type	Meaning
`ready`	The on-device traffic producer connected.
`flow`	A decoded HTTP exchange or an interception failure.
`websocket-message`	An application WebSocket message associated with a flow.
`gap`	Events were dropped because the bounded device queue overflowed.

Event schema

Stream hello

The gateway sends a hello message immediately after the WebSocket opens. This message uses camelCase fields and is separate from the device event envelope:

{
  "type": "hello",
  "schemaVersion": 1,
  "sessionId": "9a675d1d-f919-4454-9523-9715f1fc1057",
  "deviceId": "3fe83936-fb09-49f1-8ec8-c1bdca194cf1",
  "state": "active",
  "retention": "none"
}

Device event envelope

All subsequent device events use snake_case fields:

Field	Type	Required	Description
`type`	String	Yes	`ready`, `flow`, `websocket-message`, or `gap`.
`session_id`	String	Yes	Traffic session UUID.
`timestamp_ms`	Non-negative integer	No	Unix timestamp in milliseconds. The current Android producer includes it on every event.

The ingest boundary rejects undeclared or duplicate fields, malformed Base64, negative numeric values, and payloads that exceed the session body limit. A ready event has no additional fields:

{
  "type": "ready",
  "session_id": "9a675d1d-f919-4454-9523-9715f1fc1057",
  "timestamp_ms": 1787234404000
}

Flow events

A flow event adds a flow object. Only id and decryption_status are always present; other fields can be omitted or null when an interception fails before that information is available.

{
  "type": "flow",
  "session_id": "9a675d1d-f919-4454-9523-9715f1fc1057",
  "timestamp_ms": 1787234404123,
  "flow": {
    "id": "mitm-flow-id",
    "decryption_status": "decrypted",
    "host": "example.com",
    "port": 443,
    "sni": "example.com",
    "scheme": "https",
    "http_version": "HTTP/2",
    "method": "GET",
    "path": "/api/items",
    "status_code": 200,
    "request_headers": [["content-type", "application/json"]],
    "response_headers": [["content-type", "application/json"]],
    "request_body_base64": null,
    "response_body_base64": "eyJvayI6dHJ1ZX0=",
    "request_body_bytes": 0,
    "response_body_bytes": 11,
    "request_body_truncated": false,
    "response_body_truncated": false,
    "duration_ms": 84
  }
}

Field	Type	Required	Description
`id`	String	Yes	Unique flow identifier.
`decryption_status`	String	Yes	Current producer values are `decrypted` and `failed`.
`error`	String or null	No	Safe interception or transport error. It can be present even when a response was decoded.
`host`	String or null	No	HTTP request host.
`port`	Non-negative integer or null	No	Upstream server port.
`sni`	String or null	No	TLS Server Name Indication.
`scheme`	String or null	No	Request scheme, such as `http` or `https`.
`http_version`	String or null	No	Negotiated protocol reported by the app connection, such as `HTTP/1.1`, `HTTP/2`, or `HTTP/3`.
`method`	String or null	No	HTTP request method.
`path`	String or null	No	Request path including its query string.
`status_code`	Non-negative integer or null	No	HTTP response status code; absent or null if no response was received.
`request_headers`	Array of string pairs or null	No	Request headers as `[[name, value], ...]`. Repeated names remain separate pairs.
`response_headers`	Array of string pairs or null	No	Response headers in the same shape.
`request_body_base64`	Base64 string or null	No	Captured request body, limited by the session’s `maxBodyBytes`.
`response_body_base64`	Base64 string or null	No	Captured response body, limited by the session’s `maxBodyBytes`.
`request_body_bytes`	Non-negative integer or null	No	Original request-body size before truncation.
`response_body_bytes`	Non-negative integer or null	No	Original response-body size before truncation.
`request_body_truncated`	Boolean or null	No	`true` when the request body exceeded `maxBodyBytes`.
`response_body_truncated`	Boolean or null	No	`true` when the response body exceeded `maxBodyBytes`.
`duration_ms`	Non-negative integer or null	No	Time from request start to response completion in milliseconds.

There is no combined url field. Construct one from scheme, host, optional port, and path if your parser needs it. A null body field means that no body bytes were captured. Use the corresponding *_body_bytes and *_body_truncated fields to distinguish an empty body from one clipped by the session limit.

WebSocket message events

Application WebSocket messages refer back to their HTTP upgrade flow by flow_id:

{
  "type": "websocket-message",
  "session_id": "9a675d1d-f919-4454-9523-9715f1fc1057",
  "timestamp_ms": 1787234405123,
  "message": {
    "flow_id": "mitm-flow-id",
    "direction": "client",
    "opcode": "text",
    "payload_base64": "aGVsbG8=",
    "payload_bytes": 5,
    "payload_truncated": false
  }
}

Field	Type	Required	Description
`flow_id`	String	Yes	ID of the associated HTTP upgrade flow.
`direction`	String	Yes	Current producer values are `client` and `server`.
`opcode`	String	Yes	Current producer values are `text` and `binary`.
`payload_base64`	Base64 string or null	No	Captured message payload, limited by `maxBodyBytes`.
`payload_bytes`	Non-negative integer or null	No	Original payload size before truncation.
`payload_truncated`	Boolean or null	No	`true` when the payload exceeded `maxBodyBytes`.

Gap events

A gap event reports that the device queue dropped one or more events:

{
  "type": "gap",
  "session_id": "9a675d1d-f919-4454-9523-9715f1fc1057",
  "timestamp_ms": 1787234406123,
  "dropped_events": 1
}

dropped_events is a required positive integer. The event does not identify which flows or messages were dropped. For example, decode response bodies with jq:

websocat --no-async-stdio -B 8388608 \
  -H="Authorization: Bearer $MOBILERUN_API_KEY" \
  -H="Sec-WebSocket-Protocol: $STREAM_PROTOCOL" \
  "$STREAM_URL" \
  | jq --unbuffered -r \
      'select(.type == "flow" and .flow.response_body_base64) | .flow.response_body_base64 | @base64d'

Inspected headers and bodies can contain credentials, personal data, and other secrets. Mobilerun does not retain session events, but anything you print, pipe, or redirect locally may be stored on your machine.

Interception behavior

Inspection is transparent at the device-networking layer. You do not need to configure an HTTP proxy in the app or Android settings. Starting a session temporarily installs the capture CA and reconfigures the device’s existing TUN routing; stopping the session restores the previous routing and trust-store mounts. Android’s global http_proxy setting is neither required nor modified. Certificate pinning is not bypassed. A pinned app can reject the inspection certificate before an HTTP request is available, causing the connection to fail without a decoded flow. If the failure reaches the HTTP flow pipeline, the stream reports decryption_status: "failed" with an error, but clients should not assume every rejected TLS handshake produces an event. Keep using an authorized Frida pinning bypass, or equivalent instrumentation for a native or custom trust store, when inspecting pinned apps.

Stop the session

Stop inspection when you are finished so the device can restore its normal routing and temporary trust changes:

curl --fail-with-body -sS -X DELETE \
  -H "Authorization: Bearer $MOBILERUN_API_KEY" \
  "$MOBILERUN_API/devices/$DEVICE_ID/traffic/sessions/$SESSION_ID" \
  | jq '{id, state}'

The request returns 202 Accepted while cleanup runs. Repeating it is safe. Sessions also stop automatically when they expire.

Troubleshooting

TRAFFIC_NOT_SUPPORTED — The device image does not support network inspection.
TRAFFIC_NOT_ENTITLED — capabilities.trafficInspection is false; create a device in an enabled pool or contact support.
TRAFFIC_ALREADY_ACTIVE — Another session is starting, active, or stopping. Use the session ID in details.sessionId, or list sessions with GET /devices/{deviceId}/traffic/sessions.
TRAFFIC_DEVICE_NOT_READY — Wait until the device reaches the ready state and retry with the same idempotency key.
401 Unauthorized on the WebSocket — For CLI clients, send your dr_sk_... API key as Authorization: Bearer .... For browsers, append the returned stream.token as the URL’s token query parameter. Do not send stream.token as a Bearer token.
WebSocket subprotocol error — Send Sec-WebSocket-Protocol: mobilerun.traffic.v1 with either authentication method.
Incoming message too long or a jq parse error — Increase websocat’s message buffer with -B; do not use -S, because strict mode drops oversized inspection events. Use --no-async-stdio when piping large messages on macOS.
The socket closed with 1013 — Reconnect with the same authentication method. Read the session status again first if the device may have been transferred or replaced. Missed events are not replayed.

Introduction

Concepts

Guides

Dashboard

Agent Skills

Integrations

Network inspection

Requirements

Endpoints

Start an inspection session

Wait until the session is active

Stream events with websocat

Browser WebSocket clients

Event schema

Stream hello

Device event envelope

Flow events

WebSocket message events

Gap events

Interception behavior

Stop the session

Troubleshooting

​Requirements

​Endpoints

​Start an inspection session

​Wait until the session is active

​Stream events with websocat

​Browser WebSocket clients

​Event schema

​Stream hello

​Device event envelope

​Flow events

​WebSocket message events

​Gap events

​Interception behavior

​Stop the session

​Troubleshooting

Requirements

Endpoints

Start an inspection session

Wait until the session is active

Stream events with websocat

Browser WebSocket clients

Event schema

Stream hello

Device event envelope

Flow events

WebSocket message events

Gap events

Interception behavior

Stop the session

Troubleshooting