*REST API › Endpoint reference › Platform › AI*

# Ask the AI about your data

> Answers in natural language a question about the data of your account, optionally also searching the web.

It NEVER writes anything: the engine runs without a single write tool loaded, and what it can read is bounded by the permission guardrail of the owner of the API key, table by table. It consumes AI credits of the account: without quota it responds 402 addon_required without ever asking the model. It can take tens of seconds on questions that chain several queries; if `needsMoreContext` comes true, the answer is empty and you should rephrase with more detail instead of retrying the same.

`POST /api/v1/ai/ask` — scope `ai:ask`

Scope: `ai:ask` · 120/min · Add-on (402) · MCP: `filmo_ai_ask`

## Authorizations

Bearer API key with the scope below. `ai:ask`

## Body

Body schema: `AiAskBody`

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `question` | string | Yes | Natural-language question about the data of your account. Required. |
| `webSearch` | boolean | No | Also allows web search to answer. Defaults to false: only the data of the account is consulted. = `false` |
| `mode` | string | No | Answer mode. Today only "instant" (a single pass, no conversation). Documented so that future modes are additive. `instant` = `"instant"` |

## Request examples

*Ask the AI about your data*

**cURL**

```bash
curl https://app.filmo.io/api/v1/ai/ask \
  --request POST \
  --header "Authorization: Bearer $FILMO_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "question": "¿Qué pedidos tengo confirmados la semana que viene y qué material sale en ellos?",
  "webSearch": false,
  "mode": "instant"
}'
```

**Node.js**

```javascript
fetch('https://app.filmo.io/api/v1/ai/ask', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_FILMO_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    question: '¿Qué pedidos tengo confirmados la semana que viene y qué material sale en ellos?',
    webSearch: false,
    mode: 'instant'
  })
})
```

**Python**

```python
import requests

requests.post("https://app.filmo.io/api/v1/ai/ask",
    headers={
      "Authorization": "Bearer YOUR_FILMO_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "question": "¿Qué pedidos tengo confirmados la semana que viene y qué material sale en ellos?",
      "webSearch": False,
      "mode": "instant"
    }
)
```

## Response

Response schema: `AiAskDto`

| Status | Description |
| --- | --- |
| 200 | Successful response. |
| 400 | Invalid request (validation_error): malformed query or body. `errors[]` lists every offending field with its stable code. |
| 401 | Authentication failed (unauthorized, api_key_invalid, api_key_revoked, api_key_expired, api_key_owner_inactive, api_key_owner_not_admin). |
| 402 | Add-on required (addon_required): the account plan does not include the add-on this operation needs; `requiredAddon` names it. |
| 403 | Not allowed (insufficient_scope: the API key does not have the required scope, named in `requiredScope`; forbidden: the owner of the key lacks the permission the operation requires). `insufficient_scope` is answered before the request counts against the rate limit, so it carries no `RateLimit-*` headers; `forbidden` does. |
| 404 | Resource not found (not_found): it does not exist or is outside the scope of the API key. |
| 409 | Conflict (conflict): the current state of the resource prevents the operation, a request with that Idempotency-Key is already in progress, or another conditional write (`If-Match`) held the resource for more than five seconds. `errors[0].code` says which: `in_progress` and `lock_timeout` are solved by retrying; `invalid_state` is not, because the state of the resource forbids the operation. |
| 429 | Rate limit exceeded (rate_limited): retry after `Retry-After` seconds; `RateLimit-*` says which quota ran out. |
| 500 | Internal error (internal_error). |

**200**

| Name | Type | Description |
| --- | --- | --- |
| `data` | object | The ai ask, as returned by the API. |
| `data.answer` | string | Answer in markdown. Empty string when needsMoreContext is true. |
| `data.needsMoreContext` | boolean | True when the AI finished without being able to answer and needs more context. In that case `answer` comes empty: rephrase the question with more detail instead of retrying as is. |
| `data.webSearchSources` | object[] | Cited web sources. Empty if web search was not requested or if none was used. |
| `data.webSearchSources.url` | string | URL of the consulted source. |
| `data.webSearchSources.title` | string | Source title. |
| `data.webSearchSources.favicon` | string | URL of the site favicon, to render the source. |
| `meta` | object | Additional information about the response. |
| `meta.warnings` | object[] | Lifecycle warnings; present only when the operation is deprecated. |
| `meta.warnings.code` | string | Stable warning code. `deprecated` |
| `meta.warnings.message` | string | For people: what is deprecated, until when, and what to use. |
| `meta.warnings.sunset` | string | Day (YYYY-MM-DD) the operation stops being served. |
| `meta.warnings.replacement` | string | `operationId` of the operation to use instead, or null if there is none. |
| `meta.warnings.link` | string | Where the deprecation is documented (the changelog). |

*Example response · 200*

```json
{
  "data": {
    "answer": "Example answer",
    "needsMoreContext": true,
    "webSearchSources": [
      {
        "url": "https://example.com/resource",
        "title": "Example title",
        "favicon": "Example favicon"
      }
    ]
  }
}
```

## Errors

| Status | Codes | Meaning |
| --- | --- | --- |
| 400 | `validation_error` | Malformed query or body. `errors[]` lists every offending field with its stable code. |
| 402 | `addon_required` | The account plan does not include the add-on this operation needs; `requiredAddon` names it. |
| 404 | `not_found` | It does not exist or is outside the scope of the API key. |
| 409 | `conflict` | The current state of the resource prevents the operation, a request with that Idempotency-Key is already in progress, or another conditional write (`If-Match`) held the resource for more than five seconds. `errors[0].code` says which: `in_progress` and `lock_timeout` are solved by retrying; `invalid_state` is not, because the state of the resource forbids the operation. |

## Deprecation

This operation is not deprecated. Deprecations are announced with a Deprecation header and a sunset date.

---

Canonical URL: https://docs.filmo.io/rest-api/endpoint-reference/ai/ask-the-ai-about-your-data  
Last updated: 2026-10-25