# Modal

> 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.

App · 25 actions. Web page: https://docs.lodol.com/docs/integrations/modal

## Actions

### 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_name`, text, required): The Modal Queue. Pick one, or type a name.
- Value (`value`, text, required): 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**

- `added` (true/false): Always true once added
- `length` (number): How many items the Queue now holds
- `queue_name` (text): The Queue

**Example output**

```json
{
  "added": true,
  "length": 3,
  "queue_name": "jobs"
}
```

### Cancel function call

Stop a function call started with 'Start function call'.

**Inputs**

- Call ID (`call_id`, text, required): The call's ID from 'Start function call', starting with fc-.
- Also stop its containers (`terminate_containers`, true/false): Shut down the containers running it at once, rather than letting them finish their other work. Default: `false`.

**Outputs**

- `call_id` (text): The call cancelled
- `cancelled` (true/false): Always true once cancelled

**Example output**

```json
{
  "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_name`, text, required): A name for the Secret: letters, digits, dashes, periods and underscores.
- Values (`variables`, object, required): The environment variable names and values the Secret holds, such as {"OPENAI_API_KEY": "sk-..."}. Your Modal code reads them as environment variables.

**Outputs**

- `created` (true/false): Always true once created
- `keys` (list): The variable names it holds
- `secret_name` (text): The Secret's name

**Example output**

```json
{
  "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_name`, text, required): A name for the Volume: letters, digits, dashes, periods and underscores.

**Outputs**

- `created` (true/false): Always true once created
- `volume_name` (text): The Volume's name

**Example output**

```json
{
  "created": true,
  "volume_name": "results"
}
```

### Delete dict

Delete a Modal Dict and everything stored in it.

**Inputs**

- Dict (`dict_name`, text, required): The Modal Dict. Pick one, or type a name.

**Outputs**

- `deleted` (true/false): Always true once deleted
- `dict_name` (text): The Dict deleted

**Example output**

```json
{
  "deleted": true,
  "dict_name": "settings"
}
```

### Delete file

Delete a file, or a folder and everything in it, from a Volume.

**Inputs**

- Volume (`volume_name`, text, required): The Modal Volume. Pick one, or type its name.
- File (`path`, text, required): The file's path in the Volume, such as /results/output.json.
- Delete a whole folder (`recursive`, true/false): Needed to delete a folder that has files in it. Default: `false`.

**Outputs**

- `deleted` (true/false): Always true once deleted
- `path` (text): What was deleted

**Example output**

```json
{
  "deleted": true,
  "path": "/results/output.json"
}
```

### Delete queue

Delete a Modal Queue and every item still in it.

**Inputs**

- Queue (`queue_name`, text, required): The Modal Queue. Pick one, or type a name.

**Outputs**

- `deleted` (true/false): Always true once deleted
- `queue_name` (text): The Queue deleted

**Example output**

```json
{
  "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_name`, text, required): The Modal Secret. Pick one, or type its name.

**Outputs**

- `deleted` (true/false): Always true once deleted
- `secret_name` (text): The Secret deleted

**Example output**

```json
{
  "deleted": true,
  "secret_name": "openai-key"
}
```

### Delete volume

Delete a Volume and every file in it. This can't be undone.

**Inputs**

- Volume (`volume_name`, text, required): The Modal Volume. Pick one, or type its name.

**Outputs**

- `deleted` (true/false): Always true once deleted
- `volume_name` (text): The Volume deleted

**Example output**

```json
{
  "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_name`, text, required): The deployed Modal app. Pick one, or type its name.

**Outputs**

- `app` (object): The app

**Example output**

```json
{
  "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_name`, text, required): The Modal Dict. Pick one, or type a name.
- Key (`key`, text, required): The key the value is stored under.

**Outputs**

- `dict_name` (text): The Dict
- `found` (true/false): False when the Dict has no such key
- `key` (text): The key
- `value` (object): The value, or null when not found

**Example output**

```json
{
  "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**

- `apps` (list): The apps
- `count` (number): How many there are

**Example output**

```json
{
  "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_name`, text, required): The Modal Volume. Pick one, or type its name.
- Folder (`path`, text): The folder to list, such as /results. Leave empty for the top.
- Include subfolders (`recursive`, true/false): Also list everything inside the folders it contains. Default: `false`.

**Outputs**

- `count` (number): How many there are
- `files` (list): The files and folders

**Example output**

```json
{
  "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**

- `count` (number): How many there are
- `secrets` (list): The Secrets, without their values

**Example output**

```json
{
  "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**

- `count` (number): How many there are
- `volumes` (list): The Volumes

**Example output**

```json
{
  "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_name`, text, required): The Modal Volume. Pick one, or type its name.
- File (`path`, text, required): The file's path in the Volume, such as /results/output.json.

**Outputs**

- `content` (text): The file's contents
- `encoding` (text): text, or base64 for a file that isn't text
- `path` (text): The file's path
- `size` (number): Its size in bytes

**Example output**

```json
{
  "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 (`command`, text, required): The shell command to run, such as python -c "print(2 + 2)". Several lines run one after another.
- Container image (`image`, text): 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 (`gpu`, text): 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_count`, number): How many of that GPU, 1 to 8. Defaults to 1. From 1 to 8.
- CPU cores (`cpu`, number): CPU cores to reserve, such as 0.5 or 4. Defaults to Modal's. From 0.125 to 64.
- Memory (MB) (`memory_mb`, number): Memory to reserve, in megabytes. Defaults to Modal's. From 128 to 262144.
- Time limit (seconds) (`timeout_seconds`, number): Stop the command after this long, 10 to 600 seconds. Defaults to 300. From 10 to 600.
- Secrets (`secret_names`, list): Secrets whose values the command gets as environment variables.
- Volume (`volume_name`, text): A Volume to make available at /data, to read inputs from or save results to.
- App (`app_name`, text): The app the sandbox is filed under in Modal's dashboard. Defaults to lodol-sandboxes, made the first time it's used.

**Outputs**

- `app_name` (text): The app the sandbox ran under
- `exit_code` (number): The command's exit code; 0 means success
- `output_truncated` (true/false): True when only the last million characters were kept
- `sandbox_id` (text): The sandbox's ID in Modal
- `stderr` (text): The command's error output
- `stdout` (text): What the command printed
- `succeeded` (true/false): True when the exit code is 0

**Example output**

```json
{
  "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_name`, text, required): The deployed Modal app. Pick one, or type its name.
- Function (`function_name`, text, required): The function in that app, by the name it has in your code (for a class method, ClassName.method).
- Arguments (`arguments`, object): 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_seconds`, number): 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_id` (text): The call's ID in Modal
- `result` (object): What the function returned

**Example output**

```json
{
  "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_name`, text, required): The Modal Dict. Pick one, or type a name.
- Key (`key`, text, required): The key the value is stored under.
- Value (`value`, text, required): 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_name` (text): The Dict
- `key` (text): The key
- `saved` (true/false): Always true once stored

**Example output**

```json
{
  "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_name`, text, required): The deployed Modal app. Pick one, or type its name.
- Function (`function_name`, text, required): The function in that app, by the name it has in your code (for a class method, ClassName.method).
- Arguments (`arguments`, object): 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_id` (text): The call's ID, starting with fc-
- `status` (text): Always running

**Example output**

```json
{
  "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_name`, text, required): The deployed Modal app. Pick one, or type its name.

**Outputs**

- `app_id` (text): Its ID
- `app_name` (text): The app stopped
- `stopped` (true/false): Always true once stopped

**Example output**

```json
{
  "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_name`, text, required): The Modal Queue. Pick one, or type a name.
- Wait for an item (seconds) (`wait_seconds`, number): How long to wait when the Queue is empty, 0 to 60 seconds. Defaults to 0: don't wait. From 0 to 60.

**Outputs**

- `found` (true/false): False when the Queue was empty
- `queue_name` (text): The Queue
- `value` (object): The item, or null when the Queue was empty

**Example output**

```json
{
  "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_name`, text, required): The Modal Secret. Pick one, or type its name.
- Values (`variables`, object, required): The environment variable names and values the Secret holds, such as {"OPENAI_API_KEY": "sk-..."}. Your Modal code reads them as environment variables.

**Outputs**

- `keys` (list): The variable names set
- `secret_name` (text): The Secret's name
- `updated` (true/false): Always true once updated

**Example output**

```json
{
  "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_id`, text, required): The call's ID from 'Start function call', starting with fc-.

**Outputs**

- `call_id` (text): The call's ID
- `result` (object): What the function returned
- `status` (text): Always finished

**Example output**

```json
{
  "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_name`, text, required): The Modal Volume. Pick one, or type its name.
- File (`path`, text, required): Where to save it in the Volume, such as /inputs/data.csv.
- Contents (`content`, text, required): What to put in the file.
- Contents are base64 (`content_is_base64`, true/false): Turn on when the contents are a file encoded as base64 rather than text. Default: `false`.
- Replace an existing file (`overwrite`, true/false): Replace a file already at that path. When off, an existing file stops the step. Default: `true`.

**Outputs**

- `path` (text): The file's path
- `size` (number): Its size in bytes
- `written` (true/false): Always true once saved

**Example output**

```json
{
  "path": "/inputs/data.csv",
  "size": 1280,
  "written": true
}
```
