diff --git a/content/docs/overview/sessions-api/session-lifecycle.mdx b/content/docs/overview/sessions-api/session-lifecycle.mdx
index daf0d56e..201f7b0b 100644
--- a/content/docs/overview/sessions-api/session-lifecycle.mdx
+++ b/content/docs/overview/sessions-api/session-lifecycle.mdx
@@ -21,9 +21,15 @@ Browser sessions are billed by the minute, rounded up. Launch sessions can last
Understanding how sessions live and die helps you manage resources effectively and build more reliable applications.
-### Reserving a Session ID
+### Tying a Session to Your Own Records
-Steel generates a session ID for you, but `create` also accepts one. Pass your own UUID when the ID has to exist before the browser does: a job row you write before starting the session, or a live view link you hand to a user while the browser is still booting.
+To track a session in your own system, such as a job row that you write before the browser starts, put your own ID in `metadata` and save the `id` that `create` returns.
+
+:::callout
+type: warn
+### Custom session IDs are deprecated
+Passing your own `sessionId` to `create` is deprecated, and Steel will reject it in a future release. Steel generates every session ID, because the ID records where the session runs. Put your own ID in `metadata` instead.
+:::
@@ -33,12 +39,12 @@ import Steel from 'steel-sdk';
const client = new Steel();
-// Reserve the ID first, then create the session with it.
-const sessionId = randomUUID();
-await jobs.insert({ sessionId, status: 'starting' });
+// Write your own record first, then create the session with its ID in metadata.
+const jobId = randomUUID();
+await jobs.insert({ jobId, status: 'starting' });
-const session = await client.sessions.create({ sessionId });
-console.log(session.id === sessionId); // true
+const session = await client.sessions.create({ metadata: { job_id: jobId } });
+await jobs.update(jobId, { sessionId: session.id, status: 'running' });
```
@@ -48,22 +54,39 @@ from steel import Steel
client = Steel()
-# Reserve the ID first, then create the session with it.
-session_id = str(uuid.uuid4())
-jobs.insert(session_id=session_id, status="starting")
+# Write your own record first, then create the session with its ID in metadata.
+job_id = str(uuid.uuid4())
+jobs.insert(job_id=job_id, status="starting")
+
+session = client.sessions.create(metadata={"job_id": job_id})
+jobs.update(job_id, session_id=session.id, status="running")
+```
+
-session = client.sessions.create(session_id=session_id)
-print(session.id == session_id) # True
+If your process stops before it saves `session.id`, find the session by its `job_id` and release it. See [Find Sessions by Metadata](/overview/sessions-api/session-metadata#find-sessions-by-metadata).
+
+
+
+```typescript !! Typescript -wcn
+for await (const session of client.sessions.list({ metadata: { job_id: jobId } })) {
+ await client.sessions.release(session.id);
+}
+```
+
+
+```python !! Python -wcn
+for session in client.sessions.list(metadata={"job_id": job_id}):
+ client.sessions.release(session.id)
```
-The value must be a valid UUID such as `123e4567-e89b-12d3-a456-426614174000`. Omit `sessionId` and Steel generates one instead. Either way, the ID goes to the same places:
+Use the `id` that `create` returns everywhere after that:
-* `client.sessions.release(sessionId)` to end the session
+* `client.sessions.release(session.id)` to end the session
-* `client.sessions.files.list(sessionId)` and the rest of the Files API
+* `client.sessions.files.list(session.id)` and the rest of the Files API
-* `wss://connect.steel.dev?apiKey=&sessionId=` to attach Playwright or Puppeteer
+* `wss://connect.steel.dev?apiKey=&sessionId=` to attach Playwright or Puppeteer
### Session Lifetime and Timeout