Recordings

Record and replay your browser sessions for debugging and analysis

AI agent instructions

Read the Notte skill and follow its setup instructions when setting up Notte or building browser automation. This is the shared source for CLI setup, authentication, and the browser-to-code workflow.

Notte automatically records every action in your browser sessions, allowing you to download video replays for debugging and analysis. Calling session.replay() (or GET /sessions/{session_id}/replay) returns a ReplayResponse with mp4_url, a presigned URL for the MP4 file. Use that URL directly, or download with replay.download().

Quick Start

Get a recording after your session ends:

quick_start.py

from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    session.execute(type="goto", url="https://example.com")
    session.execute(type="click", selector="button.submit")
    session.execute(type="fill", selector="input[name='email']", value="[e-mail]")
    # All actions automatically recorded

# Get replay after session ends
replay = session.replay()
replay.download("session_recording.mp4")

What Gets Recorded

Session recordings capture:

• Page navigation - All page loads and URL changes
• User interactions - Clicks, fills, scrolls, key presses
• DOM changes - Dynamic content updates
• Visual state - What the browser displays
• Timing - Real-time playback speed

Session Replays

Download as MP4

download_mp4.py

from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    session.execute(type="goto", url="https://example.com")
    session.execute(type="click", selector="a.link")

# Download recording
replay = session.replay()

# Save to file
replay.download("my_automation.mp4")

# Or access the presigned URL directly
print(f"MP4 URL: {replay.mp4_url}")
print(f"Expires at: {replay.expires_at}")

Replay response (mp4_url)

The replay endpoint returns JSON. The field you usually want is mp4_url:

Field	Description
mp4_url	Presigned URL to download the MP4 recording
playlist_content	HLS playlist with presigned segment URLs (for streaming)
expires_at	When the presigned URLs expire (1 hour after the request)
video_start_ms	Video start offset in milliseconds
video_duration_ms	Video duration in milliseconds

REST example:

curl "https://api.notte.cc/sessions/{session_id}/replay" \
  -H "Authorization: Bearer $NOTTE_API_KEY"

{
  "mp4_url": "https://storage.example.com/replays/session_abc.mp4?X-Amz-Signature=...",
  "playlist_content": "#EXTM3U\n...",
  "expires_at": "2026-08-06T18:00:00+00:00",
  "video_start_ms": 0,
  "video_duration_ms": 45200
}

Full API reference: Session Replay.

Replay by Session ID

Get a replay for any session using its ID:

replay_by_id.py

from notte_sdk import NotteClient

client = NotteClient()

# Get replay for a specific session
replay = client.sessions.replay(session_id="your-session-id")
replay.download("session_replay.mp4")

Agent Replays

After running an agent, get the replay from the session:

agent_replay.py

from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    agent = client.Agent(session=session, max_steps=10)
    result = agent.run(task="Find the contact email on example.com")

# Get replay from the session
replay = session.replay()
replay.download("agent_run.mp4")

agent_replay_alt.py

from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    pass  # session actions here

# Get replay after session ends
replay = session.replay()
replay.download("agent_run.mp4")

Debugging Failed Runs

Use recordings to understand what went wrong:

debug_failed.py

from notte_sdk import NotteClient

client = NotteClient()

session_id = None

try:
    with client.Session() as session:
        session_id = session.session_id
        session.execute(type="goto", url="https://example.com")
        session.execute(type="click", selector="button.sometimes-missing")

except Exception as e:
    print(f"Automation failed: {e}")

    if session_id:
        # Get recording to see what happened
        replay = client.sessions.replay(session_id=session_id)
        replay.download(f"failed_{session_id}.mp4")
        print("Replay saved for analysis")

Best Practices

1. Name Recordings Meaningfully

Use descriptive filenames:

name_recordings.py

from datetime import datetime

from notte_sdk import NotteClient

client = NotteClient()

with client.Session() as session:
    session.execute(type="goto", url="https://example.com")

# The replay is generated once the session is closed
replay = session.replay()
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
replay.download(f"login_test_{session.session_id}_{timestamp}.mp4")

2. Record Only on Failures

For production, save recordings only when something goes wrong:

record_on_failures.py

from notte_sdk import NotteClient

client = NotteClient()

try:
    with client.Session() as session:
        session.execute(type="goto", url="https://example.com")
        # ... automation ...
except Exception:
    if "session" in locals():
        try:
            replay = session.replay()
            replay.download(f"error_{session.session_id}.mp4")
        except Exception:
            pass
    raise

3. Clean Up Old Recordings

Remove old recordings to save disk space:

cleanup_old.py

import time
from pathlib import Path


def cleanup_old_recordings(directory: str, days: int = 7):
    """Remove recordings older than specified days."""
    cutoff = time.time() - (days * 86400)

    for recording in Path(directory).glob("*.mp4"):
        if recording.stat().st_mtime < cutoff:
            recording.unlink()
            print(f"Deleted: {recording}")


cleanup_old_recordings("recordings/", days=7)

Recording Limitations

What’s Recorded

• All page interactions
• Visual state changes
• Navigation and reloads
• Dynamic content

What’s NOT Recorded

• Audio
• Network request details (use GET /sessions/{session_id}/network/logs or CDP)
• Console logs (use logging)

Recording starts when the session is created, so the video also covers the time before your first action.

Storage

Recordings are:

• Stored on Notte’s servers after the session ends
• Available once the session is closed (session.replay() waits for the video to be ready)
• Accessed via the mp4_url (and optional HLS playlist) returned by session.replay() / GET /sessions/{session_id}/replay
• Downloadable as MP4 via replay.download() or by fetching mp4_url

Presigned URLs expire 1 hour after they are issued. Check expires_at (or replay.expires_at in the SDK), and call session.replay() again to get fresh URLs.

Next Steps

Live View

Watch sessions in real-time

Session Lifecycle

Understand session management

Playwright

Connect with Playwright via CDP

File Storage

Upload and download files in sessions