Modal
App · 25 actions
Run your Modal functions and GPU jobs from a workflow: call deployed functions and get their results, run commands in sandboxes, stop apps, and manage Secrets, Volumes and their files, Dicts and Queues.
Actions
| Action | What it does |
|---|---|
| Add to queue | Add an item to the end of a Modal Queue, such as a job for a worker to pick up. |
| Cancel function call | Stop a function call started with 'Start function call'. |
| Create secret | Save keys or passwords as a new Secret that your Modal functions can use as environment variables. |
| Create volume | Create a new, empty Volume. |
| Delete dict | Delete a Modal Dict and everything stored in it. |
| Delete file | Delete a file, or a folder and everything in it, from a Volume. |
| Delete queue | Delete a Modal Queue and every item still in it. |
| Delete secret | Delete a Secret. |
| Delete volume | Delete a Volume and every file in it. |
| Get app | Get one app: its state, its functions, and when and by whom it was created, deployed or stopped. |
| Get dict value | Read the value stored under a key in a Modal Dict. |
| List apps | List the apps in your Modal environment that are deployed or running, newest first, with their functions and when they were deployed. |
| List files | List the files and folders in a Volume, in one folder or everything under it. |
| List secrets | List the Secrets (saved passwords and keys for your Modal code) in your environment. |
| List volumes | List the Volumes (shared storage your Modal code reads and writes) in your environment. |
| Read file | Read a file from a Volume, up to 5 MB. |
| Run command in a sandbox | Run a shell command in a fresh, isolated container on Modal, on a GPU if you pick one, wait for it to end, and return its output and exit code. |
| Run function | Call a function in one of your deployed Modal apps with the arguments you give, wait for it to finish (up to the time you set) and return what it returned. |
| Set dict value | Store a value under a key in a Modal Dict, a shared store your Modal code can read. |
| Start function call | Start a function in one of your deployed Modal apps and carry on without waiting. |
| Stop app | Stop an app: its running containers and sandboxes shut down and its functions stop taking calls until it is deployed again. |
| Take from queue | Take the next item off a Modal Queue (it is removed from the Queue). |
| Update secret | Add or change values in a Secret, such as a new API key. |
| Wait for function call | Wait until a function call started with 'Start function call' finishes and return its result. |
| Write file | Save text (or base64 data) as a file in a Volume, up to 5 MB, for your Modal code to read. |
Add to queue
Add an item to the end of a Modal Queue, such as a job for a worker to pick up. The Queue is made if it doesn't exist.
Inputs
- Queue
queue_nametextRequired - The Modal Queue. Pick one, or type a name.
- Value
valuetextRequired - Text, a number, or JSON such as {"job": 42}; JSON is stored as the list or dict it describes, so your Modal code reads it as one.
Outputs
addedtrue/false- Always true once added
lengthnumber- How many items the Queue now holds
queue_nametext- The Queue
Example output
{
"added": true,
"length": 3,
"queue_name": "jobs"
}Cancel function call
Stop a function call started with 'Start function call'.
Inputs
- Call ID
call_idtextRequired - The call's ID from 'Start function call', starting with fc-.
- Also stop its containers
terminate_containerstrue/false - Shut down the containers running it at once, rather than letting them finish their other work.Default:
false.
Outputs
call_idtext- The call cancelled
cancelledtrue/false- Always true once cancelled
Example output
{
"call_id": "fc-01JB4XAMPLE7Q2V9N3K8D6RMT",
"cancelled": true
}Create secret
Save keys or passwords as a new Secret that your Modal functions can use as environment variables. Fails if one by that name exists.
Inputs
- Name
secret_nametextRequired - A name for the Secret: letters, digits, dashes, periods and underscores.
- Values
variablesobjectRequired - The environment variable names and values the Secret holds, such as {"OPENAI_API_KEY": "sk-..."}. Your Modal code reads them as environment variables.
Outputs
createdtrue/false- Always true once created
keyslist- The variable names it holds
secret_nametext- The Secret's name
Example output
{
"created": true,
"keys": [
"OPENAI_API_KEY"
],
"secret_name": "openai-key"
}Create volume
Create a new, empty Volume. Fails if one by that name exists.
Inputs
- Name
volume_nametextRequired - A name for the Volume: letters, digits, dashes, periods and underscores.
Outputs
createdtrue/false- Always true once created
volume_nametext- The Volume's name
Example output
{
"created": true,
"volume_name": "results"
}Delete dict
Delete a Modal Dict and everything stored in it.
Inputs
- Dict
dict_nametextRequired - The Modal Dict. Pick one, or type a name.
Outputs
deletedtrue/false- Always true once deleted
dict_nametext- The Dict deleted
Example output
{
"deleted": true,
"dict_name": "settings"
}Delete file
Delete a file, or a folder and everything in it, from a Volume.
Inputs
- Volume
volume_nametextRequired - The Modal Volume. Pick one, or type its name.
- File
pathtextRequired - The file's path in the Volume, such as /results/output.json.
- Delete a whole folder
recursivetrue/false - Needed to delete a folder that has files in it.Default:
false.
Outputs
deletedtrue/false- Always true once deleted
pathtext- What was deleted
Example output
{
"deleted": true,
"path": "/results/output.json"
}Delete queue
Delete a Modal Queue and every item still in it.
Inputs
- Queue
queue_nametextRequired - The Modal Queue. Pick one, or type a name.
Outputs
deletedtrue/false- Always true once deleted
queue_nametext- The Queue deleted
Example output
{
"deleted": true,
"queue_name": "jobs"
}Delete secret
Delete a Secret. Apps that use it can no longer start until it is replaced.
Inputs
- Secret
secret_nametextRequired - The Modal Secret. Pick one, or type its name.
Outputs
deletedtrue/false- Always true once deleted
secret_nametext- The Secret deleted
Example output
{
"deleted": true,
"secret_name": "openai-key"
}Delete volume
Delete a Volume and every file in it. This can't be undone.
Inputs
- Volume
volume_nametextRequired - The Modal Volume. Pick one, or type its name.
Outputs
deletedtrue/false- Always true once deleted
volume_nametext- The Volume deleted
Example output
{
"deleted": true,
"volume_name": "results"
}Get app
Get one app: its state, its functions, and when and by whom it was created, deployed or stopped.
Inputs
- App
app_nametextRequired - The deployed Modal app. Pick one, or type its name.
Outputs
appobject- The app
Example output
{
"app": {
"app_id": "ap-1a2B3c4D5e6F7g8H9i0J",
"created_at": "2026-10-20T09:00:00+00:00",
"created_by": "jo",
"deployed_at": "2026-10-28T14:30:00+00:00",
"deployed_by": "jo",
"description": "image-tools",
"functions": [
"caption",
"resize"
],
"name": "image-tools",
"servers": [],
"state": "deployed",
"stopped_at": null,
"stopped_by": null,
"version": 3
}
}Get dict value
Read the value stored under a key in a Modal Dict.
Inputs
- Dict
dict_nametextRequired - The Modal Dict. Pick one, or type a name.
- Key
keytextRequired - The key the value is stored under.
Outputs
dict_nametext- The Dict
foundtrue/false- False when the Dict has no such key
keytext- The key
valueobject- The value, or null when not found
Example output
{
"dict_name": "settings",
"found": true,
"key": "threshold",
"value": 0.8
}List apps
List the apps in your Modal environment that are deployed or running, newest first, with their functions and when they were deployed.
Inputs
None.
Outputs
appslist- The apps
countnumber- How many there are
Example output
{
"apps": [
{
"app_id": "ap-1a2B3c4D5e6F7g8H9i0J",
"created_at": "2026-10-20T09:00:00+00:00",
"created_by": "jo",
"deployed_at": "2026-10-28T14:30:00+00:00",
"deployed_by": "jo",
"description": "image-tools",
"functions": [
"caption",
"resize"
],
"name": "image-tools",
"servers": [],
"state": "deployed",
"stopped_at": null,
"stopped_by": null,
"version": 3
}
],
"count": 1
}List files
List the files and folders in a Volume, in one folder or everything under it.
Inputs
- Volume
volume_nametextRequired - The Modal Volume. Pick one, or type its name.
- Folder
pathtext - The folder to list, such as /results. Leave empty for the top.
- Include subfolders
recursivetrue/false - Also list everything inside the folders it contains.Default:
false.
Outputs
countnumber- How many there are
fileslist- The files and folders
Example output
{
"count": 1,
"files": [
{
"modified_at": "2026-10-29T14:31:00+00:00",
"mtime": 1793284260,
"path": "/results/output.json",
"size": 2048,
"type": "file"
}
]
}List secrets
List the Secrets (saved passwords and keys for your Modal code) in your environment.
Inputs
None.
Outputs
countnumber- How many there are
secretslist- The Secrets, without their values
Example output
{
"count": 1,
"secrets": [
{
"created_at": "2026-10-20T09:00:00+00:00",
"created_by": "jo",
"id": "st-1a2B3c4D5e6F7g8H9i0J",
"name": "openai-key"
}
]
}List volumes
List the Volumes (shared storage your Modal code reads and writes) in your environment.
Inputs
None.
Outputs
countnumber- How many there are
volumeslist- The Volumes
Example output
{
"count": 1,
"volumes": [
{
"created_at": "2026-10-20T09:00:00+00:00",
"created_by": "jo",
"id": "vo-1a2B3c",
"name": "results"
}
]
}Read file
Read a file from a Volume, up to 5 MB. Text comes back as text; anything else as base64.
Inputs
- Volume
volume_nametextRequired - The Modal Volume. Pick one, or type its name.
- File
pathtextRequired - The file's path in the Volume, such as /results/output.json.
Outputs
contenttext- The file's contents
encodingtext- text, or base64 for a file that isn't text
pathtext- The file's path
sizenumber- Its size in bytes
Example output
{
"content": "{\"score\": 0.93}",
"encoding": "text",
"path": "/results/output.json",
"size": 16
}Run command in a sandbox
Run a shell command in a fresh, isolated container on Modal, on a GPU if you pick one, wait for it to end, and return its output and exit code. The container is removed afterwards.
Inputs
- Command
commandtextRequired - The shell command to run, such as python -c "print(2 + 2)". Several lines run one after another.
- Container image
imagetext - A public image from Docker Hub or another registry, such as python:3.13-slim or pytorch/pytorch:latest. Leave empty for Modal's standard Debian image with Python.
- GPU
gputext - A GPU to attach. Leave empty to run on CPU only.One of:
T4(NVIDIA T4),L4(NVIDIA L4),A10(NVIDIA A10),L40S(NVIDIA L40S),A100(NVIDIA A100 (40 or 80 GB)),A100-40GB(NVIDIA A100 40 GB),A100-80GB(NVIDIA A100 80 GB),RTX-PRO-6000(NVIDIA RTX PRO 6000),H100(NVIDIA H100),H200(NVIDIA H200),B200(NVIDIA B200),B300(NVIDIA B300). - Number of GPUs
gpu_countnumber - How many of that GPU, 1 to 8. Defaults to 1.From 1 to 8.
- CPU cores
cpunumber - CPU cores to reserve, such as 0.5 or 4. Defaults to Modal's.From 0.125 to 64.
- Memory (MB)
memory_mbnumber - Memory to reserve, in megabytes. Defaults to Modal's.From 128 to 262144.
- Time limit (seconds)
timeout_secondsnumber - Stop the command after this long, 10 to 600 seconds. Defaults to 300.From 10 to 600.
- Secrets
secret_nameslist - Secrets whose values the command gets as environment variables.
- Volume
volume_nametext - A Volume to make available at /data, to read inputs from or save results to.
- App
app_nametext - The app the sandbox is filed under in Modal's dashboard. Defaults to lodol-sandboxes, made the first time it's used.
Outputs
app_nametext- The app the sandbox ran under
exit_codenumber- The command's exit code; 0 means success
output_truncatedtrue/false- True when only the last million characters were kept
sandbox_idtext- The sandbox's ID in Modal
stderrtext- The command's error output
stdouttext- What the command printed
succeededtrue/false- True when the exit code is 0
Example output
{
"app_name": "lodol-sandboxes",
"exit_code": 0,
"output_truncated": false,
"sandbox_id": "sb-1a2B3c4D5e6F7g8H9i0J",
"stderr": "",
"stdout": "4\n",
"succeeded": true
}Run function
Call a function in one of your deployed Modal apps with the arguments you give, wait for it to finish (up to the time you set) and return what it returned.
Inputs
- App
app_nametextRequired - The deployed Modal app. Pick one, or type its name.
- Function
function_nametextRequired - The function in that app, by the name it has in your code (for a class method, ClassName.method).
- Arguments
argumentsobject - The function's inputs, by parameter name: for def summarize(text, length) give {"text": "...", "length": 3}. Leave empty for a function that takes none.
- Wait at most (seconds)
wait_secondsnumber - How long to wait for the result, 1 to 600 seconds. Defaults to 60. For longer jobs use 'Start function call'.From 1 to 600.
Outputs
call_idtext- The call's ID in Modal
resultobject- What the function returned
Example output
{
"call_id": "fc-01JB4XAMPLE7Q2V9N3K8D6RMT",
"result": {
"caption": "A dog on a beach"
}
}Set dict value
Store a value under a key in a Modal Dict, a shared store your Modal code can read. The Dict is made if it doesn't exist.
Inputs
- Dict
dict_nametextRequired - The Modal Dict. Pick one, or type a name.
- Key
keytextRequired - The key the value is stored under.
- Value
valuetextRequired - Text, a number, or JSON such as {"job": 42}; JSON is stored as the list or dict it describes, so your Modal code reads it as one.
Outputs
dict_nametext- The Dict
keytext- The key
savedtrue/false- Always true once stored
Example output
{
"dict_name": "settings",
"key": "threshold",
"saved": true
}Start function call
Start a function in one of your deployed Modal apps and carry on without waiting. Use the call ID with 'Wait for function call' to get its result, or 'Cancel function call' to stop it.
Inputs
- App
app_nametextRequired - The deployed Modal app. Pick one, or type its name.
- Function
function_nametextRequired - The function in that app, by the name it has in your code (for a class method, ClassName.method).
- Arguments
argumentsobject - The function's inputs, by parameter name: for def summarize(text, length) give {"text": "...", "length": 3}. Leave empty for a function that takes none.
Outputs
call_idtext- The call's ID, starting with fc-
statustext- Always running
Example output
{
"call_id": "fc-01JB4XAMPLE7Q2V9N3K8D6RMT",
"status": "running"
}Stop app
Stop an app: its running containers and sandboxes shut down and its functions stop taking calls until it is deployed again.
Inputs
- App
app_nametextRequired - The deployed Modal app. Pick one, or type its name.
Outputs
app_idtext- Its ID
app_nametext- The app stopped
stoppedtrue/false- Always true once stopped
Example output
{
"app_id": "ap-1a2B3c4D5e6F7g8H9i0J",
"app_name": "image-tools",
"stopped": true
}Take from queue
Take the next item off a Modal Queue (it is removed from the Queue). Returns found false when the Queue is empty.
Inputs
- Queue
queue_nametextRequired - The Modal Queue. Pick one, or type a name.
- Wait for an item (seconds)
wait_secondsnumber - How long to wait when the Queue is empty, 0 to 60 seconds. Defaults to 0: don't wait.From 0 to 60.
Outputs
foundtrue/false- False when the Queue was empty
queue_nametext- The Queue
valueobject- The item, or null when the Queue was empty
Example output
{
"found": true,
"queue_name": "jobs",
"value": {
"job": 42
}
}Update secret
Add or change values in a Secret, such as a new API key. Values you don't name stay as they are.
Inputs
- Secret
secret_nametextRequired - The Modal Secret. Pick one, or type its name.
- Values
variablesobjectRequired - The environment variable names and values the Secret holds, such as {"OPENAI_API_KEY": "sk-..."}. Your Modal code reads them as environment variables.
Outputs
keyslist- The variable names set
secret_nametext- The Secret's name
updatedtrue/false- Always true once updated
Example output
{
"keys": [
"OPENAI_API_KEY"
],
"secret_name": "openai-key",
"updated": true
}Wait for function call
Wait until a function call started with 'Start function call' finishes and return its result. While it runs, the workflow pauses and looks again every minute.
Inputs
- Call ID
call_idtextRequired - The call's ID from 'Start function call', starting with fc-.
Outputs
call_idtext- The call's ID
resultobject- What the function returned
statustext- Always finished
Example output
{
"call_id": "fc-01JB4XAMPLE7Q2V9N3K8D6RMT",
"result": [
1,
4,
9
],
"status": "finished"
}Write file
Save text (or base64 data) as a file in a Volume, up to 5 MB, for your Modal code to read. Folders in the path are made as needed.
Inputs
- Volume
volume_nametextRequired - The Modal Volume. Pick one, or type its name.
- File
pathtextRequired - Where to save it in the Volume, such as /inputs/data.csv.
- Contents
contenttextRequired - What to put in the file.
- Contents are base64
content_is_base64true/false - Turn on when the contents are a file encoded as base64 rather than text.Default:
false. - Replace an existing file
overwritetrue/false - Replace a file already at that path. When off, an existing file stops the step.Default:
true.
Outputs
pathtext- The file's path
sizenumber- Its size in bytes
writtentrue/false- Always true once saved
Example output
{
"path": "/inputs/data.csv",
"size": 1280,
"written": true
}