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.
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.
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);
}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)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
}#[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:
npx tsx metadata.mtspython metadata.pygo run .cargo runThe 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 method | Endpoint | What it does |
|---|---|---|
updateMetadata (update_metadata in Python and Rust, UpdateMetadata in Go) | PATCH / | 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 / | 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:
const { metadata } = await client.sessions.updateMetadata(session.id, {
metadata: { outcome: "success", attempt: null },
});
console.log(metadata);result = client.sessions.update_metadata(
session.id,
metadata={"outcome": "success", "attempt": None},
)
print(result.metadata)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))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:
{ "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" },
});client.sessions.replace_metadata(
session.id,
metadata={"job_id": "job-1042", "owner": "data-team"},
)_, 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
}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.
for await (const session of client.sessions.list({
metadata: { customer: "acme", job_id: "job-1042" },
})) {
console.log(session.id, session.status);
}for session in client.sessions.list(
metadata={"customer": "acme", "job_id": "job-1042"},
):
print(session.id, session.status)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
}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, it prints that session. Rust prints the status as Released.
82a965d5-5ec1-4d06-86db-6758892a96a7 releasedOver 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
signalfilter. 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
| 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. 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.