Session Metadata

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.

1
import Steel from 'steel-sdk';
2

3
const client = new Steel();
4

5
const session = await client.sessions.create({
6
  metadata: {
7
    job_id: 'job-1042',
8
    customer: 'acme',
9
    attempt: 1,
10
  },
11
});
12

13
console.log(session.metadata);

Steel stores every value as a string. Numbers and booleans come back in their string form, so 1 comes back as "1":

1
{
2
  "job_id": "job-1042",
3
  "customer": "acme",
4
  "attempt": "1"
5
}

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.

1
const { metadata } = await client.sessions.updateMetadata(session.id, {
2
  metadata: {
3
    outcome: 'success',
4
    attempt: null,
5
  },
6
});
7

8
console.log(metadata);

The response contains the merged metadata:

1
{
2
  "metadata": {
3
    "job_id": "job-1042",
4
    "customer": "acme",
5
    "outcome": "success"
6
  }
7
}

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.

1
await client.sessions.replaceMetadata(session.id, {
2
  metadata: { job_id: 'job-1042', owner: 'data-team' },
3
});
4

5
await client.sessions.replaceMetadata(session.id, { metadata: {} });

Use updateMetadata unless you want to remove every key that you don't send.

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.

1
for await (const session of client.sessions.list({
2
  metadata: { customer: 'acme', job_id: 'job-1042' },
3
})) {
4
  console.log(session.id, session.status);
5
}

The SDK fetches every page for you. Over HTTP, send each key in bracket form and follow nextCursor until it is null:

1
curl -G https://api.steel.dev/v1/sessions \
2
  -H "steel-api-key: $STEEL_API_KEY" \
3
  --data-urlencode "metadata[customer]=acme" \
4
  --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.
• To find sessions in a job that hit a CAPTCHA or a bot block, add a signal filter. See Session Signals.

Limits

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.