---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/sessions/metadata
markdown_url: https://steel.dev/docs/sessions/metadata.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Add metadata
description: Attach your own keys and values to a session, change them while it runs, and use them to find sessions later.
summary: Attach your own keys and values to a session, change them while it runs, and use them to find sessions later.
type: how-to
reviewed: 2026-11-12
prerequisites:
  - https://steel.dev/docs/sessions/lifecycle.md
related:
  - https://steel.dev/docs/sessions/timeouts.md
  - https://steel.dev/docs/sessions/devices.md
  - https://steel.dev/docs/sessions/bandwidth.md
  - https://steel.dev/docs/sessions/files.md
  - https://steel.dev/docs/sessions/extensions.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Add metadata

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](https://steel.dev/docs/sessions/metadata#find-sessions-by-metadata).

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

> **Note**
>
> Metadata needs `steel-sdk` 0.21.0 or later, in TypeScript and in Python.

## Before you begin

Put your Steel API key in the `STEEL_API_KEY` environment variable, and install the Steel SDK for your language: [TypeScript](https://steel.dev/docs/reference/sdks/typescript#install), [Python](https://steel.dev/docs/reference/sdks/python#install), [Go](https://steel.dev/docs/reference/sdks/go#install) or [Rust](https://steel.dev/docs/reference/sdks/rust#install).

## 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.

**TypeScript**

```ts file=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);
}
```

**Python**

```python file=metadata.py
import json

from steel import Steel

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

try:
    print(json.dumps(session.metadata, indent=2))
finally:
    client.sessions.release(session.id)
```

**Go**

```go file=main.go
package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log"

	"github.com/steel-dev/sdk/go"
	"github.com/steel-dev/sdk/go/shared"
)

func main() {
	if err := run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context) error {
	client := steel.NewClient()
	session, err := client.Sessions.New(ctx, steel.SessionNewParams{
		Metadata: steel.F(map[string]steel.SessionNewParamsMetadataUnion{
			"job_id":   shared.UnionString("job-1042"),
			"customer": shared.UnionString("acme"),
			"attempt":  shared.UnionFloat(1),
		}),
	})
	if err != nil {
		return err
	}
	defer func() {
		if _, err := client.Sessions.Release(ctx, session.ID); err != nil {
			log.Print(err)
		}
	}()

	out, err := json.MarshalIndent(session.Metadata, "", "  ")
	if err != nil {
		return err
	}
	fmt.Println(string(out))
	return nil
}
```

**Rust**

```rust file=src/main.rs
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = steel_rs::Client::new();
    let session = client
        .sessions()
        .create(steel_rs::SessionCreateParams {
            metadata: Some(std::collections::HashMap::from([
                (
                    "job_id".to_owned(),
                    steel_rs::SessionCreateParamsMetadata::String("job-1042".to_owned()),
                ),
                (
                    "customer".to_owned(),
                    steel_rs::SessionCreateParamsMetadata::String("acme".to_owned()),
                ),
                (
                    "attempt".to_owned(),
                    steel_rs::SessionCreateParamsMetadata::Number(1.0),
                ),
            ])),
            ..Default::default()
        })
        .await?;

    let result: Result<(), Box<dyn std::error::Error>> = async {
        println!("{}", serde_json::to_string_pretty(&session.metadata)?);
        Ok(())
    }
    .await;

    client.sessions().release(&session.id).await?;
    result
}
```

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

**TypeScript**

```sh
npx tsx metadata.mts
```

**Python**

```sh
python metadata.py
```

**Go**

```sh
go run .
```

**Rust**

```sh
cargo run
```

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

```json nocopy
{
  "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 method | Endpoint | What it does |
| - | - | - |
| `updateMetadata` (`update_metadata` in Python and Rust, `UpdateMetadata` in Go) | `PATCH /v1/sessions/{id}/metadata` | Changes 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}/metadata` | Replaces 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`:

**TypeScript**

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

**Python**

```python
result = client.sessions.update_metadata(
    session.id,
    metadata={"outcome": "success", "attempt": None},
)
print(result.metadata)
```

**Go**

```go
result, err := client.Sessions.UpdateMetadata(ctx, session.ID, steel.SessionUpdateMetadataParams{
	Metadata: steel.F(map[string]steel.SessionUpdateMetadataParamsMetadataUnion{
		"outcome": shared.UnionString("success"),
		"attempt": nil,
	}),
})
if err != nil {
	return err
}
out, err = json.MarshalIndent(result.Metadata, "", "  ")
if err != nil {
	return err
}
fmt.Println(string(out))
```

**Rust**

```rust
let metadata = client
    .sessions()
    .update_metadata(
        &session.id,
        steel_rs::SessionUpdateMetadataParams::new(std::collections::HashMap::from([
            (
                "outcome".to_owned(),
                Some(steel_rs::SessionUpdateMetadataParamsMetadata::String(
                    "success".to_owned(),
                )),
            ),
            ("attempt".to_owned(), None),
        ])),
    )
    .await?
    .metadata;
println!("{}", serde_json::to_string_pretty(&metadata)?);
```

The response holds the merged metadata:

```json nocopy
{ "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`:

**TypeScript**

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

**Python**

```python
client.sessions.replace_metadata(
    session.id,
    metadata={"job_id": "job-1042", "owner": "data-team"},
)
```

**Go**

```go
_, err = client.Sessions.ReplaceMetadata(ctx, session.ID, steel.SessionReplaceMetadataParams{
	Metadata: steel.F(map[string]steel.SessionReplaceMetadataParamsMetadataUnion{
		"job_id": shared.UnionString("job-1042"),
		"owner":  shared.UnionString("data-team"),
	}),
})
if err != nil {
	return err
}
```

**Rust**

```rust
client
    .sessions()
    .replace_metadata(
        &session.id,
        steel_rs::SessionReplaceMetadataParams::new(std::collections::HashMap::from([
            (
                "job_id".to_owned(),
                steel_rs::SessionReplaceMetadataParamsMetadata::String(
                    "job-1042".to_owned(),
                ),
            ),
            (
                "owner".to_owned(),
                steel_rs::SessionReplaceMetadataParamsMetadata::String(
                    "data-team".to_owned(),
                ),
            ),
        ])),
    )
    .await?;
```

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`.

**TypeScript**

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

**Python**

```python
for session in client.sessions.list(
    metadata={"customer": "acme", "job_id": "job-1042"},
):
    print(session.id, session.status)
```

**Go**

```go
iter := client.Sessions.ListAutoPaging(ctx, steel.SessionListParams{
	Metadata: steel.F(map[string]string{"customer": "acme", "job_id": "job-1042"}),
})
for iter.Next() {
	session := iter.Current()
	fmt.Println(session.ID, session.Status)
}
if err := iter.Err(); err != nil {
	return err
}
```

**Rust**

```rust
let sessions = client
    .sessions()
    .list_auto_paging(steel_rs::SessionListParams {
        metadata: Some(std::collections::HashMap::from([
            ("customer".to_owned(), "acme".to_owned()),
            ("job_id".to_owned(), "job-1042".to_owned()),
        ])),
        ..Default::default()
    });
let mut sessions = std::pin::pin!(sessions);
while let Some(session) = futures_util::StreamExt::next(&mut sessions).await {
    let session = session?;
    println!("{} {:?}", 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](https://steel.dev/docs/sessions/metadata#set-metadata-at-creation), it prints that session. Rust prints the status as `Released`.

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

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

```sh
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](https://steel.dev/docs/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](https://steel.dev/docs/observability/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](https://steel.dev/docs/sessions/metadata#find-sessions-by-metadata): the session is in the result.

## Limits

| Rule | Limit |
| - | - |
| Keys | Up to 50 for each session. |
| Size | Up to 8192 bytes, measured as UTF-8 JSON. |
| Key names | Start with a letter. Use only letters, digits, `_`, `.` and `-`. Up to 64 characters. |
| Reserved keys | Keys that start with `steel_`. |
| Values | Strings of up to 1024 characters, numbers, or booleans. |
| Keys in one update | Up to 100 in one `updateMetadata` call. |
| Keys in one filter | Up 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

- [Track cost per customer](https://steel.dev/docs/production/track-cost-per-customer): Add up what the sessions with each `customer` value cost.
- [Run sessions at scale](https://steel.dev/docs/production/run-sessions-at-scale#always-release-sessions): Release the live sessions that carry a job's `job_id` when the job ends.
