Get

ts
import { Eyeball, type ExecutionSource } from "@eyeball/sdk";

const eyeball = new Eyeball({
  apiKey: process.env.EYEBALL_API_KEY!,
  baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});
const execution = await eyeball.executions.get("exe_01JZ6WA0Q73ZQ5B51SRYB6M4Z8");
console.log(execution.status);

if (execution.replayed === true) {
  console.log("An accepted replay reused this execution ID");
}

const sourceHandlers = {
  voice_session(source: Extract<ExecutionSource, { kind: "voice_session" }>) {
    console.log("Voice session", source.sessionId);
  },
} satisfies {
  [Kind in ExecutionSource["kind"]]: (
    source: Extract<ExecutionSource, { kind: Kind }>,
  ) => void;
};

if (execution.source) sourceHandlers[execution.source.kind](execution.source);

for (const fileId of execution.attachments?.fileIds ?? []) {
  console.log("Historical staged file", fileId);
}

List

ts
import { Eyeball } from "@eyeball/sdk";

const eyeball = new Eyeball({
  apiKey: process.env.EYEBALL_API_KEY!,
  baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});
const page = await eyeball.executions.list({
  status: "failed",
  tool: "gmail.send_email",
  userId: "demo_user",
  limit: 25,
});
console.log(page.executions, page.nextCursor);

Filters are status, tool, userId, cursor, and limit.

Cancel

ts
import { Eyeball } from "@eyeball/sdk";

const eyeball = new Eyeball({
  apiKey: process.env.EYEBALL_API_KEY!,
  baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});
const cancelled = await eyeball.executions.cancel(
  "exe_01JZ6WA0Q73ZQ5B51SRYB6M4Z8",
);

if (cancelled.cancellation.dispatchMayHaveBegun) {
  console.warn("Upstream work or external side effects may still complete.");
}

cancel sends a bodyless POST and returns the full immutable cancelled record. A repeated call returns the same record and resumes any incomplete usage, webhook, or queue reconciliation. It throws normalized 404, 403, 409, and server errors; 409 invalid_input means a succeeded or failed record won before cancellation.

Wait

ts
import { Eyeball } from "@eyeball/sdk";

const eyeball = new Eyeball({
  apiKey: process.env.EYEBALL_API_KEY!,
  baseUrl: process.env.EYEBALL_EXECUTOR_URL!,
});
const terminal = await eyeball.executions.wait(
  "exe_01JZ6WA0Q73ZQ5B51SRYB6M4Z8",
  { pollMs: 500, timeoutMs: 60_000 },
);
console.log(terminal.status);

wait polls until succeeded, failed, or cancelled and throws a normalized timeout error when its local deadline expires.

The optional provenance fields are bounded public metadata: replayed records an accepted replay of the same execution, source identifies a verified voice session, and attachments contains only distinct staged-file IDs and their count. No execution SDK method reveals canonical input, raw or derived idempotency identity, connection selection, or file bytes.

See the generated Executions API for filters, pagination, polling controls, and execution record unions.