diff --git a/content/docs/overview/sessions-api/configuration.mdx b/content/docs/overview/sessions-api/configuration.mdx index acb5b9c6..a6c6220a 100644 --- a/content/docs/overview/sessions-api/configuration.mdx +++ b/content/docs/overview/sessions-api/configuration.mdx @@ -62,6 +62,7 @@ If you know the browser behavior that the task needs, use this table. | Set the browser window size | `dimensions` | [Browser interface](#browser-interface) | | Use fullscreen mode | `fullscreen: true` | [Browser interface](#browser-interface) | | Select the project context | `projectId`, `namespace` | [Project context](#project-context) | +| Tag the session with your own IDs | `metadata` | [Session Metadata](/overview/sessions-api/session-metadata) | `useProxy` accepts `true`, `false`, or a configuration object. Properties such as `geolocation` are part of the `useProxy` object. diff --git a/content/docs/overview/sessions-api/meta.json b/content/docs/overview/sessions-api/meta.json index 178be6ba..66fdb43d 100644 --- a/content/docs/overview/sessions-api/meta.json +++ b/content/docs/overview/sessions-api/meta.json @@ -7,6 +7,8 @@ "quickstart", "configuration", "session-lifecycle", + "session-metadata", + "session-signals", "mobile-mode", "fullscreen-mode", "dedicated-ips", diff --git a/content/docs/overview/sessions-api/session-lifecycle.mdx b/content/docs/overview/sessions-api/session-lifecycle.mdx index 1dc5d413..4fd43bdf 100644 --- a/content/docs/overview/sessions-api/session-lifecycle.mdx +++ b/content/docs/overview/sessions-api/session-lifecycle.mdx @@ -176,6 +176,70 @@ print(response.message) # "All sessions released successfully" +### Why a Session Ended + +Every released or failed session has a `releaseReason`. It is `null` while the session is live, and for sessions created before Steel tracked the reason. + + + +```typescript !! Typescript -wcn +const session = await client.sessions.retrieve(sessionId); + +console.log(session.status, session.releaseReason); +``` + +```python !! Python -wcn +session = client.sessions.retrieve(session_id) + +print(session.status, session.release_reason) +``` + + + +| `releaseReason` | Meaning | +|---|---| +| `user_requested` | You released the session through the API or SDK. | +| `timeout` | The session reached its `timeout`. | +| `inactivity_timeout` | The session had no activity for its `inactivityTimeout`. | +| `creation_timeout` | The session did not start in time. | +| `startup_failed` | Steel could not start the browser. | +| `browser_closed` | The browser or agent closed itself. This is not a crash. | +| `browser_crashed` | The browser crashed, or its machine stopped responding. | + +### Find Past Sessions + +`sessions.list` returns sessions newest first. Filter it by status, release reason, or creation time. + + + +```typescript !! Typescript -wcn +for await (const session of client.sessions.list({ + releaseReason: 'timeout', + createdAfter: '2026-11-01T00:00:00Z', + createdBefore: '2026-11-02T00:00:00Z', +})) { + console.log(session.id, session.createdAt); +} +``` + +```python !! Python -wcn +for session in client.sessions.list( + release_reason="timeout", + created_after="2026-11-01T00:00:00Z", + created_before="2026-11-02T00:00:00Z", +): + print(session.id, session.created_at) +``` + + + +- The list leaves out failed sessions unless you pass `status` or `releaseReason`. Pass `status: 'failed'` to list failed sessions. +- `releaseReason` leaves out live sessions. Without `status`, it includes failed sessions with that reason. +- `createdAfter` includes sessions created at that exact time. `createdBefore` does not. Both take ISO 8601 timestamps. +- `totalCount` comes back only for `status: 'live'` with no metadata, signal, release reason, or date filter. For other lists, follow `nextCursor` until it is `null`. The SDK does this for you. + +To filter by your own keys or by what happened during the session, see [Session Metadata](/overview/sessions-api/session-metadata) and [Session Signals](/overview/sessions-api/session-signals). + :::callout type: help ### Need help building with the Sessions API? @@ -204,4 +268,8 @@ Set `inactivityTimeout` so the session releases itself if your side goes quiet ### How do I end a Steel session before it times out? Call `client.sessions.release(session.id)` — releasing explicitly is best practice rather than waiting for the timeout. To clean up everything at once, `client.sessions.releaseAll()` releases all active sessions. + +### How do I find Steel sessions that failed or timed out? + +Call `client.sessions.list({ status: 'failed' })` for failed sessions, or filter by `releaseReason`, such as `timeout` or `browser_crashed`. The default list leaves failed sessions out. Each session's `releaseReason` tells you why it ended. ::: diff --git a/content/docs/overview/sessions-api/session-metadata.mdx b/content/docs/overview/sessions-api/session-metadata.mdx new file mode 100644 index 00000000..5213831b --- /dev/null +++ b/content/docs/overview/sessions-api/session-metadata.mdx @@ -0,0 +1,189 @@ +--- +title: Session Metadata +sidebarTitle: Session Metadata +description: Attach your own key-value pairs to Steel sessions, change them during or after a run, and find sessions by them later. +llm: true +publishedAt: "2026-11-04" +--- + +### Overview + +Session metadata is a flat set of key-value pairs that you attach to a session. Use it to store your own identifiers, such as a job ID, a customer, or an environment. Steel returns metadata on every session response and shows it on the session page in the dashboard, so don't store secrets in it. + + + +```typescript !! Typescript -wcn +import Steel from 'steel-sdk'; + +const client = new Steel(); + +const session = await client.sessions.create({ + metadata: { + job_id: 'job-1042', + customer: 'acme', + attempt: 1, + }, +}); + +console.log(session.metadata); +``` + +```python !! Python -wcn +from steel import Steel + +client = Steel() + +session = client.sessions.create( + metadata={ + "job_id": "job-1042", + "customer": "acme", + "attempt": 1, + }, +) + +print(session.metadata) +``` + + + +Steel stores every value as a string. Numbers and booleans come back in their string form, so `1` comes back as `"1"`: + +```json JSON -wcn +{ + "job_id": "job-1042", + "customer": "acme", + "attempt": "1" +} +``` + +### Update Metadata + +`updateMetadata` changes only the keys that you send. Set a key to `null` to remove it. Keys that you leave out keep their values. You can update metadata while the session runs and after it ends. + + + +```typescript !! Typescript -wcn +const { metadata } = await client.sessions.updateMetadata(session.id, { + metadata: { + outcome: 'success', + attempt: null, + }, +}); + +console.log(metadata); +``` + +```python !! Python -wcn +result = client.sessions.update_metadata( + session.id, + metadata={ + "outcome": "success", + "attempt": None, + }, +) + +print(result.metadata) +``` + + + +The response contains the merged metadata: + +```json JSON -wcn +{ + "metadata": { + "job_id": "job-1042", + "customer": "acme", + "outcome": "success" + } +} +``` + +Each update is atomic. If two updates change different keys at the same time, Steel keeps both changes. + +### Replace Metadata + +`replaceMetadata` replaces the whole object. Send an empty object to clear it. If two replacements arrive at the same time, the last one wins. + + + +```typescript !! Typescript -wcn +await client.sessions.replaceMetadata(session.id, { + metadata: { job_id: 'job-1042', owner: 'data-team' }, +}); + +await client.sessions.replaceMetadata(session.id, { metadata: {} }); +``` + +```python !! Python -wcn +client.sessions.replace_metadata( + session.id, + metadata={"job_id": "job-1042", "owner": "data-team"}, +) + +client.sessions.replace_metadata(session.id, metadata={}) +``` + + + +Use `updateMetadata` unless you want to remove every key that you don't send. + +| SDK method | Endpoint | Behavior | +|---|---|---| +| `updateMetadata` (`update_metadata` in Python) | `PATCH /v1/sessions/{id}/metadata` | Merges the keys that you send. `null` removes a key. | +| `replaceMetadata` (`replace_metadata` in Python) | `PUT /v1/sessions/{id}/metadata` | Replaces all keys. `{}` clears the metadata. | + +### Find Sessions by Metadata + +Pass `metadata` to `sessions.list` to find sessions with matching values. Each value must match the stored string exactly. If you pass several keys, a session must match all of them. + + + +```typescript !! Typescript -wcn +for await (const session of client.sessions.list({ + metadata: { customer: 'acme', job_id: 'job-1042' }, +})) { + console.log(session.id, session.status); +} +``` + +```python !! Python -wcn +for session in client.sessions.list( + metadata={"customer": "acme", "job_id": "job-1042"}, +): + print(session.id, session.status) +``` + + + +The SDK fetches every page for you. Over HTTP, send each key in bracket form and follow `nextCursor` until it is `null`: + +```bash cURL -wcn +curl -G https://api.steel.dev/v1/sessions \ + -H "steel-api-key: $STEEL_API_KEY" \ + --data-urlencode "metadata[customer]=acme" \ + --data-urlencode "metadata[job_id]=job-1042" +``` + +- Filter values are strings. Pass `attempt: '1'` to match a value that you sent as `1`. +- The list leaves out failed sessions unless you pass `status` or `releaseReason`. See [Find Past Sessions](/overview/sessions-api/session-lifecycle#find-past-sessions). +- To find sessions in a job that hit a CAPTCHA or a bot block, add a `signal` filter. See [Session Signals](/overview/sessions-api/session-signals). + +### Limits + +| Rule | Limit | +|---|---| +| Keys | Up to 50 per session | +| Size | Up to 8 KiB, measured as UTF-8 JSON | +| Key format | Starts with a letter. Uses only letters, digits, `_`, `.`, and `-`. Up to 64 characters. | +| Reserved keys | Keys that start with `steel_` | +| Values | Strings up to 1024 characters, numbers, or booleans | +| Keys per update | Up to 100 in one `updateMetadata` call | + +A request that breaks a rule fails with a `400` error that names the key. An update that would push the merged metadata past a limit fails and leaves the session unchanged. + +:::callout +type: help +### Need help with session metadata? +Reach out to us on the #help channel on [Discord](https://discord.gg/steel-dev) or [@steeldotdev](https://twitter.com/steeldotdev). +::: diff --git a/content/docs/overview/sessions-api/session-signals.mdx b/content/docs/overview/sessions-api/session-signals.mdx new file mode 100644 index 00000000..475a92be --- /dev/null +++ b/content/docs/overview/sessions-api/session-signals.mdx @@ -0,0 +1,166 @@ +--- +title: Session Signals +sidebarTitle: Session Signals +description: Read the signals Steel records on each session, such as CAPTCHAs, bot blocks, and proxy failures, and find the sessions that hit them. +llm: true +publishedAt: "2026-11-04" +--- + +### Overview + +Signals are labels that Steel adds to a session when it sees certain events during the run, such as a CAPTCHA or a bot block. You don't set signals. To attach your own labels, use [session metadata](/overview/sessions-api/session-metadata). + + + +```typescript !! Typescript -wcn +import Steel from 'steel-sdk'; + +const client = new Steel(); + +const session = await client.sessions.retrieve(sessionId); + +console.log(session.signals); +``` + +```python !! Python -wcn +from steel import Steel + +client = Steel() + +session = client.sessions.retrieve(session_id) + +print(session.signals) +``` + + + +`signals` is an array of signal names. Sessions in `sessions.list` results carry the same field: + +```json JSON -wcn +["captcha_encountered", "bot_detection_triggered"] +``` + +### Available Signals + +| Signal | What it means | +|---|---| +| `captcha_encountered` | A CAPTCHA was detected during the session. | +| `bot_detection_triggered` | A page ended on an anti-bot block or challenge that the browser did not get past. | +| `proxy_connection_failed` | The proxy connection failed or was unreliable. | +| `session_timeout_exceeded` | The session ended on its timeout or inactivity limit. | +| `context_restored` | The session restored a previously saved browser context. | + +For the exact reason a session ended, read its `releaseReason`. See [Why a Session Ended](/overview/sessions-api/session-lifecycle#why-a-session-ended). + +### When Signals Appear + +Steel adds signals to a session when the session ends. While the session runs, `signals` is an empty array. Steel fills it in within a few seconds after release. + + + +```typescript !! Typescript -wcn +await client.sessions.release(session.id); + +await new Promise((resolve) => setTimeout(resolve, 10_000)); + +const { signals } = await client.sessions.retrieve(session.id); +``` + +```python !! Python -wcn +import time + +client.sessions.release(session.id) + +time.sleep(10) + +signals = client.sessions.retrieve(session.id).signals +``` + + + +An empty array doesn't prove that nothing happened. Detection uses heuristics and doesn't cover every case. A signal records that Steel saw the event at some point in the session. It doesn't describe the final state of the page. + +### Look Up Signal Definitions + +`signalCatalog` returns the current signals with a label and a description for each. Use it to show signals in your own UI without hardcoding the list. + + + +```typescript !! Typescript -wcn +const catalog = await client.sessions.signalCatalog(); + +for (const signal of catalog.signals) { + console.log(signal.value, signal.label, signal.severity); +} +``` + +```python !! Python -wcn +catalog = client.sessions.signal_catalog() + +for signal in catalog.signals: + print(signal.value, signal.label, signal.severity) +``` + + + +Each entry has a `severity` of `info`, `warning`, `danger`, or `success`. The `semantics` field states the same limits as the section above: + +```json JSON -wcn +{ + "signals": [ + { + "value": "bot_detection_triggered", + "label": "Bot blocked", + "description": "A page ended on an anti-bot block or challenge that the browser did not get past", + "source": "derived", + "severity": "warning" + } + ], + "semantics": "Signals record what was observed at some point during a session, not the current page state. ..." +} +``` + +Steel can add signals over time. Handle signal values that you don't recognize. + +### Find Sessions by Signal + +Pass `signal` to `sessions.list` to find sessions that carry a signal. If you pass several signals, a session must carry all of them. Combine `signal` with `metadata` to narrow the search to one of your jobs or customers. + + + +```typescript !! Typescript -wcn +for await (const session of client.sessions.list({ + metadata: { job_id: 'job-1042' }, + signal: ['bot_detection_triggered'], +})) { + console.log(session.id, session.signals); +} +``` + +```python !! Python -wcn +for session in client.sessions.list( + metadata={"job_id": "job-1042"}, + signal=["bot_detection_triggered"], +): + print(session.id, session.signals) +``` + + + +Over HTTP, repeat the `signal` parameter for each signal: + +```bash cURL -wcn +curl -G https://api.steel.dev/v1/sessions \ + -H "steel-api-key: $STEEL_API_KEY" \ + --data-urlencode "signal=captcha_encountered" \ + --data-urlencode "signal=bot_detection_triggered" +``` + +- The list leaves out failed sessions unless you pass `status` or `releaseReason`. See [Find Past Sessions](/overview/sessions-api/session-lifecycle#find-past-sessions). +- The dashboard shows signals in the sessions list and on each session page. + +:::callout +type: help +### Need help with session signals? +Reach out to us on the #help channel on [Discord](https://discord.gg/steel-dev) or [@steeldotdev](https://twitter.com/steeldotdev). +:::