Recordings

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="user@example.com")
    # 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
`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")
    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 CDP for this)
Console logs (use logging)
Session state before first action

Storage

Recordings are:

Stored on Notte’s servers after the session ends
Accessed via the mp4_url (and optional HLS playlist) returned by session.replay() / GET /sessions/{session_id}/replay
Retained for 24 hours
Downloadable as MP4 via replay.download() or by fetching mp4_url

Recordings are deleted after 24 hours. Download them promptly if needed for later analysis. Presigned URLs also expire — check expires_at (or replay.expires_at in the SDK) for the expiration time.

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

Getting Started

Sessions

Authentication

Functions

Web API

Guides

Quick Start

What Gets Recorded

Session Replays

Download as MP4

Replay response (`mp4_url`)

Replay by Session ID

Agent Replays

Debugging Failed Runs

Best Practices

1. Name Recordings Meaningfully

2. Record Only on Failures

3. Clean Up Old Recordings

Recording Limitations

What’s Recorded

What’s NOT Recorded

Storage

Next Steps

Live View

Session Lifecycle

Playwright

File Storage

​Quick Start

​What Gets Recorded

​Session Replays

​Download as MP4

​Replay response (mp4_url)

​Replay by Session ID

​Agent Replays

​Debugging Failed Runs

​Best Practices

​1. Name Recordings Meaningfully

​2. Record Only on Failures

​3. Clean Up Old Recordings

​Recording Limitations

​What’s Recorded

​What’s NOT Recorded

​Storage

​Next Steps

Live View

Session Lifecycle

Playwright

File Storage

Quick Start

What Gets Recorded

Session Replays

Download as MP4

Replay response (`mp4_url`)

Replay by Session ID

Agent Replays

Debugging Failed Runs

Best Practices

1. Name Recordings Meaningfully

2. Record Only on Failures

3. Clean Up Old Recordings

Recording Limitations

What’s Recorded

What’s NOT Recorded

Storage

Next Steps