Skip to content

Add metadata

Set up your agent

Give your coding agent a Steel browser and the Steel skills, so that it browses and writes Steel code the right way. Learn more

Install the Steel CLI. It signs you in and installs the skills for your coding agents.

curl -fsS https://setup.steel.dev | sh

Or send this prompt to your coding agent, and it does the same:

Read https://setup.steel.dev/install.md and follow it to set up Steel for this coding client.
Then continue my requested task using the installed Steel skill.

Set up your agent →

Metadata is a flat set of keys and values that you attach to a session, so that you can tie the session to your own records and find it later. Use keys such as a job ID, a customer or an environment. Steel stores the metadata with the session, returns it in every session response, and shows it in the session viewer.

Steel generates every session ID. To tie a session to a record that you write before the session starts, such as a job row, give the record its own ID and pass that ID in metadata. Then save the session's id on the record. If your process stops before it saves the id, find the session by metadata.

Because every session response and the dashboard show it, do not store secrets in metadata.

Before you begin

Put your Steel API key in the STEEL_API_KEY environment variable, and install the Steel SDK for your language: TypeScript, Python, Go or Rust.

Set metadata at creation

Pass metadata when you create the session. A value can be a string, a number or a boolean. Steel stores every value as a string.

This program creates a session with three keys, prints the metadata that Steel stored, and releases the session.

metadata.mts
import Steel from "steel-sdk";

const client = new Steel();
const session = await client.sessions.create({
  metadata: { job_id: "job-1042", customer: "acme", attempt: 1 },
});

try {
  console.log(JSON.stringify(session.metadata, null, 2));
} finally {
  await client.sessions.release(session.id);
}

In Rust, the program also needs cargo add serde_json. Run the program:

npx tsx metadata.mts

The number 1 comes back as the string "1":

{
  "job_id": "job-1042",
  "customer": "acme",
  "attempt": "1"
}

Update or replace metadata

You can change the metadata while the session runs and after it ends, with one of these calls:

SDK methodEndpointWhat it does
updateMetadata (update_metadata in Python and Rust, UpdateMetadata in Go)PATCH /v1/sessions/{id}/metadataChanges only the keys that you send. A key set to null is removed. The other keys keep their values.
replaceMetadata (replace_metadata in Python and Rust, ReplaceMetadata in Go)PUT /v1/sessions/{id}/metadataReplaces all the keys. An empty object clears the metadata.

Use updateMetadata unless you mean to remove every key that you do not send. This call adds outcome and removes attempt:

const { metadata } = await client.sessions.updateMetadata(session.id, {
  metadata: { outcome: "success", attempt: null },
});
console.log(metadata);

The response holds the merged metadata:

{ "job_id": "job-1042", "customer": "acme", "outcome": "success" }

To replace every key, call replaceMetadata. After this call, the session has only job_id and owner:

await client.sessions.replaceMetadata(session.id, {
  metadata: { job_id: "job-1042", owner: "data-team" },
});

Each update is atomic. When two updates change different keys at the same time, Steel keeps both changes. When two replacements arrive at the same time, the last one wins.

Find sessions by metadata

Pass metadata to sessions.list. Each value must match the stored string exactly, and a session must match every key that you pass. The SDK fetches every page for you. In Go and Rust, the method that does this is ListAutoPaging or list_auto_paging.

for await (const session of client.sessions.list({
  metadata: { customer: "acme", job_id: "job-1042" },
})) {
  console.log(session.id, session.status);
}

In Rust, this code needs cargo add futures-util.

The code prints one line for each session that matches. After one run of the first program, it prints that session. Rust prints the status as Released.

82a965d5-5ec1-4d06-86db-6758892a96a7 released

Over HTTP, send each key in brackets, and follow nextCursor until it is null:

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. To match a value that you sent as the number 1, pass "1".
  • By default, the list leaves out failed sessions. List sessions shows the filters that include them.
  • To find a job's sessions that hit a CAPTCHA or a bot block, add a signal filter. See Signals.

Check that it worked

Read the session with sessions.retrieve (Sessions.Get in Go). Its metadata has the keys that you set and none that you removed, and each value is a string. The session viewer shows the same keys. To check a filter, pass one key and its value to sessions.list, as in Find sessions by metadata: the session is in the result.

Limits

RuleLimit
KeysUp to 50 for each session.
SizeUp to 8192 bytes, measured as UTF-8 JSON.
Key namesStart with a letter. Use only letters, digits, _, . and -. Up to 64 characters.
Reserved keysKeys that start with steel_.
ValuesStrings of up to 1024 characters, numbers, or booleans.
Keys in one updateUp to 100 in one updateMetadata call.
Keys in one filterUp to 50 in one sessions.list call.

A request that breaks a rule fails with 400. When one key breaks a rule, the message names the key. An update that would take the merged metadata past a limit fails, and leaves the session unchanged.

Next steps