ExecutionResource: Direct Scrape, Agent, and Headful Runs

The ExecutionResource provides direct, stateless endpoints for running browser automation without saving a task first. You can scrape a page, run an agent session, or launch a headful browser in a single call. The Figranium client also exposes these as top-level shortcuts: client.scrape(), client.agent(), and client.headful().

ExecutionResource (singular) is for direct runs. For saved-task execution, see TasksResource. For execution history and live streams, see ExecutionsResource.

import dev.figranium.sdk.Figranium
import dev.figranium.sdk.FigraniumAuthentication

val client = Figranium(
    authentication = FigraniumAuthentication.ApiKey("your-api-key"),
)

Methods

scrape

suspend inline fun <reified T> scrape(
    input: JSONObject,
    options: RequestOptions = RequestOptions(),
): ExecutionResult<T>

Performs a one-off scrape by sending POST /scrape. Pass a url, a selector for DOM extraction, or an extractionScript for custom parsing. You can also inject runtime variables via variables or taskVariables.

scrape_by_selector.kt

import kotlinx.serialization.json.*

val result = client.execution.scrape<JsonElement>(
    mapOf(
        "url" to JsonPrimitive("https://news.ycombinator.com"),
        "selector" to JsonPrimitive(".titleline > a"),
        "variables" to buildJsonObject { put("limit", 5) },
    ),
)
println(result.data)

scrape_by_script.kt

val result = client.execution.scrape<JsonElement>(
    mapOf(
        "url" to JsonPrimitive("https://example.com"),
        "extractionScript" to JsonPrimitive(
            """
            const items = Array.from(document.querySelectorAll('.item'));
            return items.map(el => el.textContent?.trim());
            """.trimIndent(),
        ),
    ),
)
println(result.data)

agent

suspend inline fun <reified T> agent(
    input: JSONObject,
    options: RequestOptions = RequestOptions(),
): ExecutionResult<T>

Runs a one-off agent session by sending POST /agent. The agent navigates and interacts autonomously based on the provided input. You can supply a runId to correlate or resume a specific run.

agent_run.kt

val result = client.execution.agent<JsonElement>(
    mapOf(
        "url" to JsonPrimitive("https://example.com"),
        "runId" to JsonPrimitive("run-2024-001"),
    ),
)
println(result.success)
println(result.data)

headful

suspend inline fun <reified T> headful(
    input: JSONObject,
    options: RequestOptions = RequestOptions(),
): ExecutionResult<T>

Launches a headful (visible) browser session by sending POST /headful. Pass a starting url and optional runtime variables. This is useful when you need to interact with a live browser window or debug visually.

headful_run.kt

val result = client.execution.headful<JsonElement>(
    mapOf(
        "url" to JsonPrimitive("https://example.com/login"),
        "variables" to buildJsonObject { put("username", "alice") },
    ),
)
println(result.runId)
println(result.data)

Top-level shortcuts

Figranium mirrors these methods at the client root so you can call them directly without reaching into execution:

shortcuts.kt

val scrapeResult = client.scrape<JsonElement>(
    mapOf(
        "url" to JsonPrimitive("https://example.com"),
        "selector" to JsonPrimitive("h1"),
    ),
)

val agentResult = client.agent<JsonElement>(
    mapOf(
        "url" to JsonPrimitive("https://example.com"),
    ),
)

val headfulResult = client.headful<JsonElement>(
    mapOf(
        "url" to JsonPrimitive("https://example.com"),
    ),
)

Return type

All three methods return ExecutionResult<T>, which includes the following fields:

Field	Type	Description
`data`	`T?`	The result payload from the run.
`outcome`	`String?`	One of `"success"`, `"error"`, `"stopped"`, `"crashed"`, or `"anti_bot"`.
`success`	`Boolean?`	Whether the execution completed successfully.
`error`	`String?`	Error message if the run failed.
`runId`	`String?`	Correlation ID for the execution.

For error handling, see /sdk/kotlin/errors. For request options such as custom headers and timeout, see /sdk/kotlin/request-options.

Tasks

Create, save, and execute named tasks.

Executions

List, inspect, and stream execution history.

Request options

Pass custom headers and per-request timeouts.

Errors

Handle FigraniumException responses.

Introduction

JavaScript SDK

Python SDK

Swift SDK

Kotlin SDK

ExecutionResource: Direct Scrape, Agent, and Headful Runs

Methods

Top-level shortcuts

Return type

Tasks

Executions

Request options

Errors

​Methods

​Top-level shortcuts

​Return type

​Related resources

Tasks

Executions

Request options

Errors

Methods

Top-level shortcuts

Return type

Related resources