> ## Documentation Index
> Fetch the complete documentation index at: /dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# apps_run

> Run one action on a connected app. Asks first.

> [!NOTE]
>
> Free · Your key and project keys · Asks the person first

Runs one action from `apps_list` as the person: search their Gmail, make a calendar event, update a Notion page. Searches and reads only read. Other actions can send, change or delete things, so it asks the person first.

> [!WARNING]
>
> Over HTTP, the first call returns `409 needs_approval`. Ask the person, then send the same call with `"approved": true`. See [Tools that ask first](/dev/docs/concepts/asks-first.md).

Call it at `POST /platform/v1/me/tools/apps_run` or, for one of your app's users, `POST /platform/v1/users/{uid}/tools/apps_run`. On MCP, your AI tool calls `apps_run` with the same arguments.

## Arguments

Send these inside `arguments`.

**name** `string` *required*

The action's name, exactly as `apps_list` gives it.

**arguments** `object` (default: null)

Arguments that match the action's `input_schema`.

**user\_timezone** `string` (default: "UTC")

The person's time zone.

## Returns

The tool's answer comes back under `result`.

**result** `any`

What the app sent back.

```bash Your key theme={"system"}
curl https://api.constella.app/platform/v1/me/tools/apps_run \
  -H "Authorization: Bearer $CONSTELLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"approved": true, "arguments": {"name": "gmail_search", "approved": true, "arguments": {"query": "from:alex pricing"}}}'
```

```bash Project key theme={"system"}
curl https://api.constella.app/platform/v1/users/u_123/tools/apps_run \
  -H "Authorization: Bearer $CONSTELLA_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"approved": true, "arguments": {"name": "gmail_search", "approved": true, "arguments": {"query": "from:alex pricing"}}}'
```

```python Python theme={"system"}
import os, requests

r = requests.post(
    "https://api.constella.app/platform/v1/me/tools/apps_run",
    headers={"Authorization": f"Bearer {os.environ['CONSTELLA_API_KEY']}", "X-Constella-Client": "my-script"},
    json={"arguments": {"name": "gmail_search", "arguments": {"query": "from:alex pricing"}}, "approved": True},
)
print(r.json()["result"])
```

```javascript JavaScript theme={"system"}
const res = await fetch("https://api.constella.app/platform/v1/me/tools/apps_run", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CONSTELLA_API_KEY}`,
    "X-Constella-Client": "my-script",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"arguments": {"name": "gmail_search", "arguments": {"query": "from:alex pricing"}}, "approved": true}),
});
const { result } = await res.json();
```

```json 200 theme={"system"}
{
  "result": {
    "messages": [
      {
        "subject": "Re: pricing",
        "from": "alex@example.com"
      }
    ]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.