Skip to content

Call a function#

Below, weather is the function of Write and publish a function, with v1 published and prod pointing at it.

What to call#

A call names a target: an alias (prod), latest (the newest version), a version (v3), or draft. Without one, latest — or the draft while nothing is published. Only the draft and the versions that latest or an alias name have instances: to call another version, point an alias at it (409 FUNCTION_VERSION_NOT_SERVED otherwise).

From the API, the CLI, Python, an assistant#

curl -sS -i 'https://api.astralyx.cloud/v1/functions/weather/invoke?target=prod' \
  -H "Authorization: Bearer $ASTRALYX_TOKEN" -H 'content-type: application/json' \
  -d '{"city": "Lisbon", "days": 2}'

HTTP/2 200
content-type: application/json
x-astraeus-invocation-id: inv-5d1f0a9c2e7b4410
x-astraeus-function-version: 1

{"city": "Lisbon", "dates": ["2026-10-07", "2026-10-08"], "max_c": [24.1, 25.3]}

astra astraeus functions invoke weather@prod -d '{"city": "Lisbon", "days": 2}'

from astralyx import astraeus
c = astraeus.Client.from_config()
print(c.invoke("weather", {"city": "Lisbon", "days": 2}, target="prod"))

Turn on the Functions toolset of the connection (Connect AI assistants): invoke_function calls one, write_function writes and publishes one, get_function_logs reads a call's lines, and set_function_alias moves an alias after you confirm it in the console.

Invoking runs code: it takes the editor (or admin) role. The input is at most 6 MiB of JSON.

Its URL#

A function whose HTTP trigger is on (spec.http.enabled, in the version that runs) answers at its URL on the workspace's gateways, with an API key of the workspace that lists it — the key's functions, or * for every one:

astra eos keys create weather-app --function weather
Gateway URL
Hosted https://inference.astralyx.cloud/v1/functions/weather@prod/invoke
On your edge machines http://<edge machine>:8800/v1/functions/weather@prod/invoke 
curl -sS https://inference.astralyx.cloud/v1/functions/weather@prod/invoke \
  -H "Authorization: Bearer $ASTRAEUS_API_KEY" -H 'content-type: application/json' \
  -d '{"city": "Lisbon"}'

weather alone is its latest version; the draft is never called at a URL. On your edge machines the gateway calls the instance itself: the input and the answer never leave your infrastructure. On the hosted gateway they pass through Astralyx's servers in memory only, and a call is limited to 90 s (1 MB of input).

Any HTTP request: …/functions/weather@prod/http/<path> passes the request to the function as an event —

{"method": "POST", "path": "/orders/7", "query": {"x": "1"},
 "headers": {"content-type": "application/json"}, "body": "{\"n\": 1}", "is_base64_encoded": false}

(a body that is not UTF-8 is base64; your Authorization is never passed on). The function's answer is the response: a returned {"status_code": 201, "headers": {...}, "body": ...} (statusCode too) sets them; anything else is 200 with it as JSON. A Python handler taking event gets it whole.

On a timetable#

A schedule can invoke a function instead of starting a run: its function_call names the function, an alias (or latest; never the draft) and the input.

{
  "metadata": {"name": "weather-every-morning"},
  "spec": {
    "schedule": {"hour": 6, "minute": 0, "timezone": "Europe/Lisbon"},
    "function_call": {"function": "weather", "alias": "prod", "input": {"city": "Lisbon", "days": 1}}
  }
}

The call is started, not waited for: what it answered is in the function's logs and metrics, with the trigger schedule.

How calls wait, and when they are refused#

  • Cold start: a target with no instance running starts one, and the call waits for it — at most 120 s (503 FUNCTION_STARTING past it; the packages may still be installing: call again).
  • Busy: each instance serves scaling.concurrency calls at once. When every slot is taken, the call waits in the queue, for at most the function's timeout (503 FUNCTION_QUEUE_TIMEOUT past it). When scaling.queue calls already wait, it is refused at once with 429 FUNCTION_BUSY (function_busy at a URL). More instances are added, up to scaling.max_instances, as the instances stay busy.
  • Its own errors are its answer: 500 {"error": {...}} when it raised, 504 past its timeout.
Code Why
404 FUNCTION_NOT_FOUND, FUNCTION_ALIAS_NOT_FOUND, FUNCTION_VERSION_NOT_FOUND No such function, alias or version.
404 FUNCTION_HTTP_DISABLED Its HTTP trigger is off.
409 FUNCTION_NOT_PUBLISHED latest, at a URL, or by a schedule, of a function with no version.
409 FUNCTION_VERSION_NOT_SERVED A version no alias names.
429 FUNCTION_BUSY Every instance is busy and the queue is full.
503 FUNCTION_STARTING, FUNCTION_QUEUE_TIMEOUT No instance in time; retry.