Execute a function

Queue a run instead of waiting for it, collect the result by task id, and control what the function receives.

Prerequisites#

An app slug and a function slug.
Credentials for the site, unless the function is public.
The function must be active. An inactive function returns 404.

Execute and wait#

A call that waits is the default shape and is covered end to end in Create, run, and delete a function. The response carries the return value in data and the invocation record alongside it, and the request waits up to the execution timeout, 900 seconds by default.

Everything below is for the other shape: work that is slow, or that nobody is waiting on.

Execute without waiting#

JavaScript SDK
Python SDK
Refine
REST API
TaruviBase Console

import {Functions} from '@taruvi/sdk';

await new Functions(client).execute('FUNCTION_SLUG', {
  params: {invoice_id: 'INV-1042'},
  async: true,
});

client.functions.execute(
    "FUNCTION_SLUG",
    params={"invoice_id": "INV-1042"},
    is_async=True,
)

Configure the named app provider using Refine setup.

import {useCustomMutation} from '@refinedev/core';

const {mutate: queue} = useCustomMutation();

// Call from an event handler.
queue({
  dataProviderName: 'app',
  url: 'FUNCTION_SLUG',
  method: 'post',
  values: {invoice_id: 'INV-1042'},
  meta: {kind: 'function', async: true},
});

For a queued run, the hook exposes the invocation at mutation.data.data. Save its celery_task_id for the result lookup.

POST/api/apps/$TARUVI_APP_SLUG/functions/$FUNCTION_SLUG/execute/

Headers

Authorization: Api-Key $TARUVI_API_KEY
Content-Type: application/json

Request body

{
  "params": {
    "invoice_id": "INV-1042"
  },
  "async": true
}

View cURL

curl -X POST "$TARUVI_SITE_URL/api/apps/$TARUVI_APP_SLUG/functions/$FUNCTION_SLUG/execute/" \
  -H "Authorization: Api-Key $TARUVI_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "params": {
    "invoice_id": "INV-1042"
  },
  "async": true
}
JSON

202Returns data as an empty list and an invocation record carrying celery_task_id.

REST and direct SDK calls receive 202 with data set to an empty list. Keep the celery_task_id from the invocation record; it is how you collect the result.

The Python SDK names this parameter is_async, while the REST body and the JavaScript SDK use async.

Read the result later#

Python SDK
REST API
TaruviBase Console

client.functions.get_result(task_id)

GET/api/result/$TASK_ID/

Headers

Authorization: Api-Key $TARUVI_API_KEY

View cURL

curl "$TARUVI_SITE_URL/api/result/$TASK_ID/" \
  -H "Authorization: Api-Key $TARUVI_API_KEY"

200Returns status, result, and traceback. Status is PENDING until the task finishes.

Read data.status; the top-level status is the response envelope's "success". On success, data.result holds the execution record: the function's return value is data.result.result in app mode, or data.result.response in proxy mode.

`data.status`	Meaning
`PENDING`	Not finished
`SUCCESS`	Finished, with the return value
`FAILURE`	Finished, with a traceback

A task ID that doesn't exist also reports PENDING, so stop polling after a bound. Nothing notifies you when a function completes, so poll at a rate that matches the work rather than tightly.

Pass parameters#

Parameters travel in params. Query-string values are merged in too, with the body winning on a key collision.

Your code receives params with three keys added by the platform: __function__, request, and __method__. The execute endpoint accepts POST, GET, PATCH, and PUT, and __method__ tells the function which verb was used, so one function can serve several.

If you omit async, the function's own default applies.

Verify#

An asynchronous call returns 202 and a task id that later resolves to SUCCESS or FAILURE.

Every execution creates an invocation record, so a run that produced no record did not start. For event-triggered functions, the usual cause is filter conditions that did not match.