Task Variables and Templates

Figranium tasks accept typed variables and reference them inside action values with a {$name} template. The Python SDK ships a variable() helper that produces the correct token, plus typed shapes for declaring variables on a Task.

Declare task variables

Task variables live under task["variables"]. Each entry has a type and a default value.

from figranium import Task

task: Task = {
    "name": "Search",
    "url": "https://example.com",
    "mode": "agent",
    "variables": {
        "query": {"type": "string", "value": "figranium"},
        "limit": {"type": "number", "value": 10},
        "strict": {"type": "boolean", "value": True},
    },
    "actions": [
        # ...
    ],
}

Variable type is "string", "number", or "boolean". Additional fields are allowed on each variable entry, and unknown fields are preserved by the SDK’s flexible task type.

Reference variables in actions

Anywhere an action expects a string value, use variable(name) to reference a task variable. The helper returns {$name}.

from figranium import actions, variable

actions.type("#search", variable("query"))
actions.set("activeQuery", variable("query"))
actions.request(
    "https://api.example.com/search",
    method="POST",
    body='{"q": "' + variable("query") + '"}',
)

variable("") raises ValueError; names must not be empty or whitespace-only.

Override at runtime

Pass variables when executing a task to override the defaults for a single run. Runtime variables use plain values, not the typed shape used at declaration time.

result = client.run_task(task_id, {
    "variables": {
        "query": "browser automation",
        "limit": 25,
    },
})

You can also pass taskVariables, which sets task-scoped defaults for the run without changing the saved task.

client.run_task(task_id, {
    "variables": {"query": "figranium"},
    "taskVariables": {"userAgent": "custom"},
})

Direct execution

scrape, agent, and headful accept the same runtime variable shape when called directly:

client.scrape({
    "url": "https://example.com",
    "variables": {"query": "figranium"},
})

See Execution resource for full input shapes.

Auto-created variables

Some server-side flows auto-create variables (for example when a script writes a result to a new name). Those entries include "autoCreated": True. The SDK preserves the flag on read and write.

Use variable() for every template reference so your code stays type-safe and refactorable. Hard-coding {$name} strings is brittle when variable names change.

Actions

Every action helper that accepts a template value.

Tasks resource

Full reference for saving and running tasks.

JavaScript SDK

Python SDK

Swift SDK

Task Variables and Templates

Declare task variables

Reference variables in actions

Override at runtime

Direct execution

Auto-created variables

Actions

Tasks resource

​Declare task variables

​Reference variables in actions

​Override at runtime

​Direct execution

​Auto-created variables

​Related

Actions

Tasks resource

Declare task variables

Reference variables in actions

Override at runtime

Direct execution

Auto-created variables

Related