Functions

Functions let you run custom Python code inside Samsara to automate workflows, process data, and integrate with external systems — without hosting your own infrastructure. Trigger Functions manually, on a schedule, via the API, or from alert workflows.

Functions are available in all Samsara cloud regions where your organization is deployed. Use the regional API base URL that matches your dashboard (cloud.samsara.com, cloud.eu.samsara.com, or cloud.ca.samsara.com) when your Function calls the Samsara REST API.

Overview

Common use cases include:

• Exchanging data between Samsara and external APIs
• Running scheduled sync jobs (for example, nightly driver or vehicle updates)
• Automating operational workflows triggered by alerts
• Building lightweight integrations without deploying separate servers

Each Function is a managed AWS Lambda running Python 3.12 in your organization's Samsara cloud. Samsara handles deployment, scheduling, credentials storage, and execution logging.

Access Functions in the dashboard

1. Log in to the Samsara dashboard.
2. Go to Settings → Developer → Functions.
3. Use the List tab to view existing Functions, or create a new one.

Permissions

Users with Standard Admin or Full Admin roles have read/write access to Functions. Read-only Admin users have read access. Other users can be granted access through a custom role permission under APIs & Integrations.

Runtime limits

If your code package is large because of Python dependencies, use pre-built Lambda layers for common libraries instead of bundling everything in the zip.

Retries

If a Function fails with a runtime error, the platform may retry the same invocation up to two additional times (three attempts total). Design write operations to be idempotent — especially API POST calls — so partial failures and retries do not create duplicate records.

Triggers

Functions can be started in four ways:

Every invocation receives an event object (Python dictionary) as the first argument to your handler. The event includes:

• Your configured event parameters (key-value pairs)
• SamsaraFunctionTriggerSource — how the run was triggered (manual, schedule, api, or alert)
• SamsaraFunctionCorrelationId — unique ID for the run; use this when viewing logs

Event parameters

Configure default parameters on the Function. During a manual run, you can override parameter values for that run only; overrides do not persist.

Parameter names must be unique. Values are passed to your handler as keys in the event dictionary.

Handler and code package

Handler format

Set the handler to {filename}.{function_name} — the Python entry point in your uploaded code.

Example: for a function named main in function.py, set the handler to:

function.main

Here, function refers to the Python function in your code, not the Samsara Function product name.

Upload a zip package

1. Write your Python code locally (any IDE).
2. Package your code and dependencies into a zip file.
3. Upload the zip in the Zipped Code Package field when creating or editing the Function.

From the directory containing your source files:

zip -r ../my_function.zip ./*

The zip must contain the handler file defined in your handler setting.

Secrets

Store API tokens, passwords, and other credentials in Secrets — never in source code or event parameters.

1. Add secrets in the Function configuration UI.
2. Load them at runtime in your handler:

import samsara

def main(event, context):
    function = samsara.Function()
    secrets = function.secrets().load()
    api_token = secrets.get("MY_API_TOKEN")
    # Use secrets for Samsara or third-party API calls

Secrets are encrypted and scoped to your organization and Function.

Storage

Function Storage lets Functions persist data across runs (files and a lightweight key/value store).

• Use the Storage tab in the dashboard to upload, download, and delete files.
• In code, use the Samsara Function storage APIs (see the persistent-storage example in our examples repository).

Enable storage for your organization before relying on it in production. Contact Samsara Support if Storage is not available on your account.

Logs

View execution logs on the Function details page:

• Select a time range (up to 7 days at a time)
• Sort by time or message
• Search within displayed log entries
• Download logs as JSON for analysis

If you do not see expected output, verify the handler path, check for runtime errors in the log stream, and confirm parameters and secrets are configured correctly.

Develop locally with samsara-fn

For faster iteration, use the samsara-fn CLI to bundle, initialize, and test Functions before uploading to Samsara.

Quick start

python3 -m venv venv
source venv/bin/activate          # Mac/Linux
# .\venv\Scripts\Activate.ps1     # Windows PowerShell

pip install samsara-fn

samsara-fn templates just-secrets my-first-func
samsara-fn bundle my-first-func .

samsara-fn init my-first-func \
  --zipFile my-first-func.zip \
  --handler function.main

samsara-fn run manual my-first-func

Run samsara-fn init --help and samsara-fn run --help for secrets, parameters, and other trigger modes (api, schedule, alertAction).

Example templates and patterns

Browse the functions-examples repository for ready-made patterns:

Download all examples: functions-examples.zip

Calling the Samsara API from a Function

Use the official Samsara Python SDK (samsara-api) for REST API calls. The SDK handles authentication when configured with your Function secrets and respects your organization's cloud region.

See also:

• REST API Overview
• API Authentication
• Base URL
• Multi-Region Deployment FAQ (if you operate in US, EU, and/or CA)

Lambda layers

Samsara provides optional Lambda layers with common Python dependencies (for example requests, boto3, paramiko, tenacity). If your zip is too large because of dependencies, contact your Samsara representative or Partner Support to request layer access rather than bundling heavy libraries yourself.

Pre-installed layer packages include: requests, boto3, botocore, paramiko, cryptography, python-dateutil, pytz, tenacity, and related dependencies.

Best practices

• Use clear Function names and descriptions (names are unique, up to 35 characters, and cannot be changed later).
• Store credentials in Secrets, not in code or event parameters.
• Double-check that your handler path matches your file structure.
• Test with different parameter values before enabling schedules or alert actions.
• If using schedules, confirm your organization timezone is correct.
• Make API writes idempotent to tolerate retries.
• Use logs and SamsaraFunctionCorrelationId when debugging failed runs.

Troubleshooting

For additional help:

• Customers: Samsara Support
• Technology partners: Partner Support
• API design questions: Developer community

FAQ

Are languages other than Python supported?
Only Python is supported today for Function code packages.

Can I run the same Function code in multiple regions?
Functions are deployed per organization in that organization's cloud region. If you operate in multiple regions, create and deploy Functions separately in each region's dashboard, and point API calls at the matching regional base URL.

How is this different from a Marketplace app or API token integration?
Marketplace apps use OAuth for customer installs and are suited for productized partner integrations. Functions are for custom code that runs inside Samsara — ideal for automations, one-org workflows, and rapid prototyping that calls the same APIs you would use from an external service.

What's on the roadmap?
Samsara continues to expand Functions capabilities. Check the changelog and contact your account team for the latest.

Related guides

• Quickstart
• Client libraries and SDKs
• Webhooks
• Partner Developer Portal
• Create and Manage Apps