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: figranium.scrape(), figranium.agent(), and figranium.headful().

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

import { Figranium } from "@figranium/sdk";

const figranium = new Figranium({ apiKey: process.env.FIGRANIUM_API_KEY! });

Methods

scrape

scrape<T = unknown>(
  input: UnknownRecord & {
    url?: string;
    selector?: string;
    extractionScript?: string;
    variables?: RuntimeVariables;
    taskVariables?: RuntimeVariables;
  },
  options?: RequestOptions
): Promise<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.ts

const result = await figranium.execution.scrape({
  url: "https://news.ycombinator.com",
  selector: ".titleline > a",
  variables: { limit: 5 },
});

console.log(result.data);

scrape-by-script.ts

const result = await figranium.execution.scrape({
  url: "https://example.com",
  extractionScript: `
    const items = Array.from(document.querySelectorAll('.item'));
    return items.map(el => el.textContent?.trim());
  `,
});

console.log(result.data);

agent

agent<T = unknown>(
  input: UnknownRecord & { runId?: string },
  options?: RequestOptions
): Promise<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.ts

const result = await figranium.execution.agent({
  url: "https://example.com",
  runId: "run-2024-001",
});

console.log(result.success, result.data);

headful

headful<T = unknown>(
  input: UnknownRecord & {
    url?: string;
    variables?: RuntimeVariables;
    taskVariables?: RuntimeVariables;
  },
  options?: RequestOptions
): Promise<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.ts

const result = await figranium.execution.headful({
  url: "https://example.com/login",
  variables: { username: "alice" },
});

console.log(result.runId, result.data);

Top-level shortcuts

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

shortcuts.ts

const scrapeResult = await figranium.scrape({ url: "https://example.com", selector: "h1" });
const agentResult  = await figranium.agent({ url: "https://example.com" });
const headfulResult = await figranium.headful({ url: "https://example.com" });

Return type

All three methods return ExecutionResult<T>, which extends UnknownRecord and includes:

Field	Type	Description
`data`	`T`	The typed result payload from the run.
`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/js/errors. For request options such as signal, timeoutMs, and custom headers, see /sdk/js/request-options.

Intro

Installation

Basics

Features

Agent Logic

API

JavaScript SDK

Integrations

Ops

Changelog

ExecutionResource: Direct Scrape, Agent, and Headful Runs

Methods

Top-level shortcuts

Return type

​Methods

​Top-level shortcuts

​Return type

Methods

Top-level shortcuts

Return type