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

ActionWhat it does
Add to queueAdd an item to the end of a Modal Queue, such as a job for a worker to pick up.
Cancel function callStop a function call started with 'Start function call'.
Create secretSave keys or passwords as a new Secret that your Modal functions can use as environment variables.
Create volumeCreate a new, empty Volume.
Delete dictDelete a Modal Dict and everything stored in it.
Delete fileDelete a file, or a folder and everything in it, from a Volume.
Delete queueDelete a Modal Queue and every item still in it.
Delete secretDelete a Secret.
Delete volumeDelete a Volume and every file in it.
Get appGet one app: its state, its functions, and when and by whom it was created, deployed or stopped.
Get dict valueRead the value stored under a key in a Modal Dict.
List appsList the apps in your Modal environment that are deployed or running, newest first, with their functions and when they were deployed.
List filesList the files and folders in a Volume, in one folder or everything under it.
List secretsList the Secrets (saved passwords and keys for your Modal code) in your environment.
List volumesList the Volumes (shared storage your Modal code reads and writes) in your environment.
Read fileRead a file from a Volume, up to 5 MB.
Run command in a sandboxRun 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 functionCall 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 valueStore a value under a key in a Modal Dict, a shared store your Modal code can read.
Start function callStart a function in one of your deployed Modal apps and carry on without waiting.
Stop appStop an app: its running containers and sandboxes shut down and its functions stop taking calls until it is deployed again.
Take from queueTake the next item off a Modal Queue (it is removed from the Queue).
Update secretAdd or change values in a Secret, such as a new API key.
Wait for function callWait until a function call started with 'Start function call' finishes and return its result.
Write fileSave 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

Queuequeue_nametextRequired
The Modal Queue. Pick one, or type a name.
ValuevaluetextRequired
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 IDcall_idtextRequired
The call's ID from 'Start function call', starting with fc-.
Also stop its containersterminate_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

Namesecret_nametextRequired
A name for the Secret: letters, digits, dashes, periods and underscores.
ValuesvariablesobjectRequired
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

Namevolume_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

Dictdict_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

Volumevolume_nametextRequired
The Modal Volume. Pick one, or type its name.
FilepathtextRequired
The file's path in the Volume, such as /results/output.json.
Delete a whole folderrecursivetrue/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

Queuequeue_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

Secretsecret_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

Volumevolume_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

Appapp_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

Dictdict_nametextRequired
The Modal Dict. Pick one, or type a name.
KeykeytextRequired
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

Volumevolume_nametextRequired
The Modal Volume. Pick one, or type its name.
Folderpathtext
The folder to list, such as /results. Leave empty for the top.
Include subfoldersrecursivetrue/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

Volumevolume_nametextRequired
The Modal Volume. Pick one, or type its name.
FilepathtextRequired
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

CommandcommandtextRequired
The shell command to run, such as python -c "print(2 + 2)". Several lines run one after another.
Container imageimagetext
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.
GPUgputext
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 GPUsgpu_countnumber
How many of that GPU, 1 to 8. Defaults to 1.From 1 to 8.
CPU corescpunumber
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.
Secretssecret_nameslist
Secrets whose values the command gets as environment variables.
Volumevolume_nametext
A Volume to make available at /data, to read inputs from or save results to.
Appapp_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

Appapp_nametextRequired
The deployed Modal app. Pick one, or type its name.
Functionfunction_nametextRequired
The function in that app, by the name it has in your code (for a class method, ClassName.method).
Argumentsargumentsobject
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

Dictdict_nametextRequired
The Modal Dict. Pick one, or type a name.
KeykeytextRequired
The key the value is stored under.
ValuevaluetextRequired
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

Appapp_nametextRequired
The deployed Modal app. Pick one, or type its name.
Functionfunction_nametextRequired
The function in that app, by the name it has in your code (for a class method, ClassName.method).
Argumentsargumentsobject
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

Appapp_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

Queuequeue_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

Secretsecret_nametextRequired
The Modal Secret. Pick one, or type its name.
ValuesvariablesobjectRequired
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 IDcall_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

Volumevolume_nametextRequired
The Modal Volume. Pick one, or type its name.
FilepathtextRequired
Where to save it in the Volume, such as /inputs/data.csv.
ContentscontenttextRequired
What to put in the file.
Contents are base64content_is_base64true/false
Turn on when the contents are a file encoded as base64 rather than text.Default: false.
Replace an existing fileoverwritetrue/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
}

On this page