Function Management

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.

Manage the lifecycle of your Functions including updates, versioning, monitoring executions, and viewing replays.

Viewing Functions

List All Functions

View your deployed Functions:

list_functions.py

from notte_sdk import NotteClient

client = NotteClient()

# List functions (one page: 10 per page by default)
functions = client.functions.list(page_size=50)

for func in functions.items:
    print(f"ID: {func.function_id}")
    print(f"Name: {func.name}")
    print(f"Version: {func.latest_version}")
    print(f"Created: {func.created_at}")
    print("---")

List calls are paginated (10 items per page by default, up to 100 with page_size). Use page and the response’s has_next to read further pages. In Python, client.functions.list() and list_runs() default to only_active=True.

Get Function Details

Retrieve specific Function information: Set function_id (Python) or functionId (Node) to your deployed Function’s ID.

from notte_sdk import NotteClient

client = NotteClient()

# Get function by ID
function = client.Function(function_id=function_id)

# Access function properties
print(f"Function ID: {function.function_id}")
print(f"Name: {function.response.name}")
print(f"Description: {function.response.description}")
print(f"Latest Version: {function.response.latest_version}")
print(f"Versions: {function.response.versions}")

import { NotteClient } from 'notte-sdk';

const client = new NotteClient();

// Get function by ID
const fn = client.NotteFunction({ function_id: functionId });
const response = await fn.get();

// Access function properties
console.log(`Function ID: ${response.function_id}`);
console.log(`Name: ${response.name}`);
console.log(`Description: ${response.description}`);
console.log(`Latest Version: ${response.latest_version}`);
console.log(`Versions: ${response.versions}`);

Updating Functions

Update Function Code

Deploy a new version of your Function:

update_code.py

from notte_sdk import NotteClient

client = NotteClient()

function = client.Function(function_id="func_abc123")

# Update with new code
function.update(path="updated_function.py")

print(f"Updated to version: {function.response.latest_version}")

Update Function Metadata

Change the name, description, or default runtime with PATCH /functions/{function_id}, or fn.updateMetadata() in TypeScript. The Python SDK has no wrapper for this call yet.

curl -X PATCH https://api.notte.cc/functions/YOUR_FUNCTION_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Price monitor", "description": "Checks competitor prices"}'

import { NotteClient } from 'notte-sdk';

const client = new NotteClient();
const fn = client.NotteFunction({ function_id: 'YOUR_FUNCTION_ID' });
await fn.updateMetadata({ name: 'Price monitor', description: 'Checks competitor prices' });

Note: Code updates create new versions automatically. Previous versions remain available for rollback.

Versioning

Version Management

Functions automatically version on each update:

from notte_sdk import NotteClient

client = NotteClient()

function = client.Function(function_id=function_id)

# Get all versions
print(f"Available versions: {function.response.versions}")

# Get latest version
print(f"Latest: {function.response.latest_version}")

import { NotteClient } from 'notte-sdk';

const client = new NotteClient();

const fn = client.NotteFunction({ function_id: functionId });
const response = await fn.get();

// Get all versions
console.log('Available versions:', response.versions);

// Get latest version
console.log(`Latest: ${response.latest_version}`);

Roll Back to a Previous Version

Cloud runs always execute the latest version. To go back to an older one, roll back with POST /functions/{function_id}/rollback and a version from versions, or fn.rollback({ version }) in TypeScript. The old code is redeployed as a new latest version:

rollback_version.py

import requests
from notte_sdk import NotteClient

client = NotteClient()

function = client.Function(function_id="func_abc123")

# Cloud runs always execute the latest version
result = function.run(url="https://example.com")

# To go back to an older version, roll back to it: its code is redeployed
# as a new latest version
print(function.response.versions)

response = requests.post(
    f"https://api.notte.cc/functions/{function.function_id}/rollback",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"version": function.response.versions[0]},
)
response.raise_for_status()
print(response.json()["latest_version"])

Version History

Track changes across versions:

from notte_sdk import NotteClient

client = NotteClient()

functions = client.functions.list()

for func in functions.items:
    print(f"Function: {func.name}")
    print(f"Versions: {', '.join(func.versions)}")
    print(f"Latest: {func.latest_version}")

import { NotteClient } from 'notte-sdk';

const client = new NotteClient();

const functions = await client.functions.list();

for (const fn of functions) {
  console.log(`Function: ${fn.name}`);
  console.log(`Versions: ${fn.versions.join(', ')}`);
  console.log(`Latest: ${fn.latest_version}`);
}

Monitoring Executions

View Run History

List recent Function executions: Before running this example, set function_id (Python) or functionId (Node) to the ID of the Function whose history you want to inspect. Pass only_active=False to include finished and failed runs.

from notte_sdk import NotteClient

client = NotteClient()

# Get recent runs
runs = client.functions.list_runs(
    function_id=function_id,
    only_active=False,  # Include completed runs
)

for run in runs.items:
    print(f"Run ID: {run.function_run_id}")
    print(f"Status: {run.status}")
    print(f"Created: {run.created_at}")
    print(f"Updated: {run.updated_at}")
    print("---")

import { NotteClient } from 'notte-sdk';

const client = new NotteClient();

// Get recent runs
const runs = await client.NotteFunction({ function_id: functionId }).runs({
  only_active: false, // Include completed runs
});

for (const run of runs.items) {
  console.log(`Run ID: ${run.function_run_id}`);
  console.log(`Status: ${run.status}`);
  console.log(`Created: ${run.created_at}`);
  console.log(`Updated: ${run.updated_at}`);
  console.log('---');
}

Check Run Status

Monitor specific execution: Set function_id and run_id (Python), or functionId and runId (Node), to your Function’s ID and the run ID returned by its execution.

from notte_sdk import NotteClient

client = NotteClient()

# Get run details
run_status = client.functions.get_run(function_id, run_id)

print(f"Status: {run_status.status}")  # "active", "closed", "failed"
print(f"Result: {run_status.result}")
print(f"Session ID: {run_status.session_id}")

import { NotteClient } from 'notte-sdk';

const client = new NotteClient();

// Get run details
const runStatus = await client.NotteFunction({ function_id: functionId }).getRun(runId);

console.log(`Status: ${runStatus.status}`); // "active", "closed", "failed"
console.log('Result:', runStatus.result);
console.log(`Session ID: ${runStatus.session_id}`);

Status values:

active - Function is currently running
closed - Function completed successfully
failed - Function encountered an error

Filter Active Runs

View only running executions:

from notte_sdk import NotteClient

client = NotteClient()

# Get only active runs
active_runs = client.functions.list_runs(function_id, only_active=True)

print(f"Active runs: {len(active_runs.items)}")

for run in active_runs.items:
    print(f"Run {run.function_run_id} - {run.status}")

import { NotteClient } from 'notte-sdk';

const client = new NotteClient();

// Get only active runs
const activeRuns = await client.NotteFunction({ function_id: functionId }).runs({ only_active: true });

console.log(`Active runs: ${activeRuns.items.length}`);

for (const run of activeRuns.items) {
  console.log(`Run ${run.function_run_id} - ${run.status}`);
}

Viewing Replays

Access Function Replay

Watch MP4 replay of Function execution:

access_replay.py

from notte_sdk import NotteClient

client = NotteClient()

function = client.Function(function_id="func_abc123")

# Run the function first
result = function.run(url="https://example.com")

# Get replay for this run (uses the session from the last run)
replay = function.replay()

# Download the replay
replay.download("function_replay.mp4")

Replay features:

Video recording of browser session
Shows all actions taken
Useful for debugging failures
Available after running a function

Replay After Run

Get replay immediately after execution:

replay_after_run.py

from notte_sdk import NotteClient

client = NotteClient()

function = client.Function(function_id="func_abc123")

# Run function
result = function.run(url="https://example.com")

# Get replay for this run (automatically uses the session from the run)
replay = function.replay()

# Download the video
replay.download("execution_replay.mp4")

Managing Runs

Stop Running Function

Cancel a long-running execution:

stop_running.py

from notte_sdk import NotteClient

client = NotteClient()

# Stop specific run
client.functions.stop_run("function_abc123", "run_xyz789")

print("Function execution stopped")

Monitoring Long Runs

Track execution progress:

import threading
import time

from notte_sdk import NotteClient

client = NotteClient()

function = client.Function(function_id=function_id)

# Create the run first so you know its ID
run_id = function.create_run().function_run_id

# run() blocks until the run finishes, so execute it in a background thread
worker = threading.Thread(
    target=function.run,
    kwargs={"function_run_id": run_id, "url": "https://example.com", "stream": False},
)
worker.start()

# Poll status while it runs
while True:
    status = client.functions.get_run(function_id, run_id)

    print(f"Status: {status.status}")

    if status.status in ["closed", "failed"]:
        print(f"Final result: {status.result}")
        break

    time.sleep(5)  # Check every 5 seconds

worker.join()

import { setTimeout as sleep } from 'node:timers/promises';
import { NotteClient } from 'notte-sdk';

const client = new NotteClient();

const fn = client.NotteFunction({ function_id: functionId });

// Create the run first so you know its ID
const { function_run_id: runId } = await fn.createRun();

// Start it without awaiting: run() resolves only when the run finishes
let callError: unknown;
const execution = fn
  .run({ url: 'https://example.com' }, { functionRunId: runId, stream: false })
  .catch((error: unknown) => {
    callError = error;
  });

// Poll status while it runs
while (true) {
  if (callError) {
    console.log('Run failed:', callError);
    break;
  }

  const status = await fn.getRun(runId);

  console.log(`Status: ${status.status}`);

  if (status.status === 'closed' || status.status === 'failed') {
    console.log('Final result:', status.result);
    break;
  }

  await sleep(5000); // Check every 5 seconds
}

await execution;

Forking Functions

Fork Shared Function

Create your own copy of a shared Function:

fork_function.py

from notte_sdk import NotteClient

client = NotteClient()

# Fork a function from marketplace or teammate
original = client.Function(function_id="func_abc123")
forked_function = original.fork()

print(f"Forked function ID: {forked_function.function_id}")
print("Original ID: func_abc123")

Use cases:

Customize shared Functions
Create templates from marketplace
Copy teammate’s Functions
Experiment without affecting original

Modify Forked Function

After forking, update as needed:

modify_forked.py

from notte_sdk import NotteClient

client = NotteClient()

# Fork function
original = client.Function(function_id="shared_function_id")
forked = original.fork()

# Update your copy
forked.update(path="my_modified_version.py")

# Run your version
result = forked.run(url="https://example.com")

Downloading Functions

Download Function Code

Retrieve Function source code:

download_code.py

from notte_sdk import NotteClient

client = NotteClient()

# Notte-managed functions also need decryption_key="..."
function = client.Function(function_id="func_abc123")

# Download function code
code = function.download()

print(code)  # Function source code

# Or download directly to a file
code = function.download(path="downloaded_function.py")

Requirements:

Only works for Functions you own or have access to
Notte-managed functions also need their decryption key, passed as decryption_key when creating the Function instance

Download for Backup

Back up all your Functions:

backup_functions.py

import os

from notte_sdk import NotteClient

client = NotteClient()

# One page of up to 100 functions; use page=2, 3, ... for more
functions = client.functions.list(page_size=100)

# Create backup directory
os.makedirs("function_backups", exist_ok=True)

for func in functions.items:
    function = client.Function(function_id=func.function_id)

    try:
        code = function.download()

        filename = f"function_backups/{func.name}_{func.latest_version}.py"
        with open(filename, "w") as f:
            f.write(code)

        print(f"Backed up: {func.name}")
    except Exception as e:
        print(f"Failed to backup {func.name}: {e}")

Deleting Functions

Delete Function

Remove a Function permanently:

delete_function.py

from notte_sdk import NotteClient

client = NotteClient()

function = client.Function(function_id="func_abc123")

# Delete function
function.delete()

print("Function deleted")

Warning:

Deletion is permanent
All versions are deleted
Cannot be undone

Make Function Public

Share Functions with others:

make_public.py

from notte_sdk import NotteClient

client = NotteClient()

# Deploy as shared
function = client.Function(
    path="my_function.py",
    name="Public Scraper",
    shared=True,  # Other users can view and fork it
)

Shared Functions:

✅ Others can view and fork
✅ Original remains under your control
❌ Others cannot modify your version

Private Functions

Keep Functions private (default):

from notte_sdk import NotteClient

client = NotteClient()

function = client.Function(
    path="my_function.py",
    name="Private Automation",
    shared=False,  # Private (default)
)

import { NotteClient } from 'notte-sdk';

const client = new NotteClient();

const fn = client.NotteFunction({
  path: 'my_function.py',
  name: 'Private Automation',
  shared: false, // Private (default)
});

Best Practices

1. Version Your Functions

Update incrementally with clear changes:

version_backup.py

from notte_sdk import NotteClient

client = NotteClient()

function = client.Function(function_id="func_abc123")

# Before major update, download current version
current_code = function.download()

# Save backup
with open(f"backups/function_v{function.response.latest_version}.py", "w") as f:
    f.write(current_code)

# Update function
function.update(path="new_version.py")

2. Monitor Function Health

Regular health checks:

function_health_check.py

from notte_sdk import NotteClient

client = NotteClient()


def check_function_health(function_id: str):
    """Check recent run success rate."""
    runs = client.functions.list_runs(function_id, only_active=False)

    total = len(runs.items)
    failed = sum(1 for r in runs.items if r.status == "failed")

    success_rate = ((total - failed) / total * 100) if total > 0 else 0

    print(f"Success rate: {success_rate:.1f}%")
    print(f"Total runs: {total}")
    print(f"Failed runs: {failed}")

    return success_rate


# Monitor function
check_function_health("func_abc123")

3. Clean Up Old Runs

Archive or analyze old execution data:

cleanup_old_runs.py

import json
from datetime import datetime, timedelta, timezone

from notte_sdk import NotteClient

client = NotteClient()


def archive_old_runs(function_id: str, days_old: int = 30):
    """Archive runs older than specified days."""
    # Most recent page of runs (up to 100), including finished ones
    runs = client.functions.list_runs(function_id, only_active=False, page_size=100)

    cutoff_date = datetime.now(timezone.utc) - timedelta(days=days_old)
    archive = []

    for run in runs.items:
        if run.created_at < cutoff_date:
            run_detail = client.functions.get_run(function_id, run.function_run_id)
            archive.append(
                {
                    "run_id": run.function_run_id,
                    "status": run.status,
                    "created_at": run.created_at.isoformat(),
                    "result": str(run_detail.result)[:100],  # First 100 chars
                }
            )

    # Save archive
    with open(f"archives/{function_id}_{datetime.now().date()}.json", "w") as f:
        json.dump(archive, f, indent=2)

    print(f"Archived {len(archive)} old runs")


archive_old_runs("function_abc123")

4. Document Changes

Keep change log for Function updates:

document_changes.py

"""
Function: Data Scraper
Function ID: func_abc123

Version History:
- v1 (2024-01-15): Initial release
- v2 (2024-01-20): Added error handling
- v3 (2024-01-25): Improved scraping accuracy
- v4 (2024-02-01): Added retry logic
"""


def run(url: str):
    # Your function code
    pass

5. Test Before Production

Validate updates before deploying:

test_before_prod.py

from notte_sdk import NotteClient


def validate_before_production():
    client = NotteClient()

    # Test locally first
    function = client.Function(function_id="func_abc123")

    # Run with local=True for testing
    test_result = function.run(url="https://test-site.com", local=True)

    if test_result.status == "closed":
        print("Test passed, ready to update production")
        function.update(path="tested_function.py")
    else:
        print(f"Test failed: {test_result.result}")

Troubleshooting

Function Fails to Run

Check run details for errors:

troubleshoot_fails.py

from notte_sdk import NotteClient

client = NotteClient()

function = client.Function(function_id="func_abc123")

run = client.functions.get_run("func_abc123", "run_xyz789")

if run.status == "failed":
    print(f"Error: {run.result}")

    # Run the function to get a replay
    result = function.run(url="https://example.com", raise_on_failure=False)
    replay = function.replay()
    replay.download("debug_replay.mp4")

Missing Secrets

Function Secrets reach your code as environment variables (see Secrets). Check for them at the start of run():

missing_env_vars.py

import os


def run():
    # Names of the Function Secrets this code expects
    required_vars = ["API_KEY", "WEBHOOK_URL"]

    missing = [var for var in required_vars if not os.environ.get(var)]

    if missing:
        return {"error": f"Missing secrets: {', '.join(missing)}"}

    # Continue with automation

High Failure Rate

Analyze failure patterns: Set function_id (Python) or functionId (Node) to your Function’s ID. Include completed runs with only_active=False / only_active: false so failed runs appear.

from notte_sdk import NotteClient

client = NotteClient()

runs = client.functions.list_runs(function_id, only_active=False)

failures = [r for r in runs.items if r.status == "failed"]

print(f"Failed runs: {len(failures)}/{len(runs.items)}")

# Analyze failure reasons
for run in failures[:5]:  # First 5 failures on this page
    run_detail = client.functions.get_run(function_id, run.function_run_id)
    print(f"Run {run.function_run_id}:")
    print(f"  Error: {run_detail.result}")
    print(f"  Time: {run.created_at}")

import { NotteClient } from 'notte-sdk';

const client = new NotteClient();

const fn = client.NotteFunction({ function_id: functionId });
const runs = await fn.runs({ only_active: false });
const failures = runs.items.filter(run => run.status === 'failed');

console.log(`Failed runs: ${failures.length}/${runs.items.length}`);

// Analyze failure reasons
for (const run of failures.slice(0, 5)) { // First 5 failures on this page
  const runDetail = await fn.getRun(run.function_run_id);
  console.log(`Run ${run.function_run_id}:`);
  console.log(`  Error: ${runDetail.result}`);
  console.log(`  Time: ${run.created_at}`);
}

Next Steps

Creating Functions

Learn how to write Functions

Invocations

Call Functions via API or SDK

Schedules

Schedule Functions with cron

Functions Concept

Back to Functions overview

​Viewing Functions

​List All Functions

​Get Function Details

​Updating Functions

​Update Function Code

​Update Function Metadata

​Versioning

​Version Management

​Roll Back to a Previous Version

​Version History

​Monitoring Executions

​View Run History

​Check Run Status

​Filter Active Runs

​Viewing Replays

​Access Function Replay

​Replay After Run

​Managing Runs

​Stop Running Function

​Monitoring Long Runs

​Forking Functions

​Fork Shared Function

​Modify Forked Function

​Downloading Functions

​Download Function Code

​Download for Backup

​Deleting Functions

​Delete Function

​Sharing Functions

​Make Function Public

​Private Functions

​Best Practices

​1. Version Your Functions

​2. Monitor Function Health

​3. Clean Up Old Runs

​4. Document Changes

​5. Test Before Production

​Troubleshooting

​Function Fails to Run

​Missing Secrets

​High Failure Rate

​Next Steps

Creating Functions

Invocations

Schedules

Functions Concept

Viewing Functions

List All Functions

Get Function Details

Updating Functions

Update Function Code

Update Function Metadata

Versioning

Version Management

Roll Back to a Previous Version

Version History

Monitoring Executions

View Run History

Check Run Status

Filter Active Runs

Viewing Replays

Access Function Replay

Replay After Run

Managing Runs

Stop Running Function

Monitoring Long Runs

Forking Functions

Fork Shared Function

Modify Forked Function

Downloading Functions

Download Function Code

Download for Backup

Deleting Functions

Delete Function

Sharing Functions

Make Function Public

Private Functions

Best Practices

1. Version Your Functions

2. Monitor Function Health

3. Clean Up Old Runs

4. Document Changes

5. Test Before Production

Troubleshooting

Function Fails to Run

Missing Secrets

High Failure Rate

Next Steps