sitemap.xml llms.txt
Skip to main content

Run Functions

Use this adapter to manage runs.

Importing the adapter​

To use the functions of the Run adapter, import it as shown:
import { runAdapter } from 'epicenter-libs';

The runAdapter namespace exports functions that make calls to the Run API.

learn more

For descriptions of the objects used by the Run adapter functions, read Run Entities.

Create​

Create run​

Call the create() function to create a run.

By default, all runs are created with the user's ID (userKey), except in the case of world-scoped runs.

If no permit is specified, the platform assigns a default determined by the session user's role and the scope boundary. For a participant creating a run, the default readLock/writeLock is USER/USER, unless that run is scoped to a world, in which case PARTICIPANT/FACILITATOR is the default. Admins and facilitators/reviewers have their own defaults.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a POST request to the /run endpoint.
  • Creates a new run using the provided model and scope parameters.
  • Automatically assigns userKey from the current session unless the run is world-scoped.
  • Optionally includes execution context, model context, permissions, and routing options.
  • Returns a RunReadOutView representing the newly created run.
Function signature
export async function create<
    V extends object = RunVariables,
    M extends object = RunMetadata,
>(
    model: string,
    scope: { userKey?: string } & GenericScope,
    optionals: RunCreateOptions = {},
): Promise<RunReadOutView<V, M>>

Parameters​

Return value​

A promise resolving to a RunReadOutView object containing details of the newly created run.

Usage example​

import { runAdapter, SCOPE_BOUNDARY } from 'epicenter-libs';

await runAdapter.create('model.py', {
    scopeBoundary: SCOPE_BOUNDARY.GROUP,
    scopeKey: '0000017dd3bf540e5ada5b1e058f08f20461'
});

Clone run​

Call the clone() function to create a copy of an existing run.

A cloned run starts with the same state as the source run. You can optionally provide new context overrides and tracking information for the cloned run.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a POST request to the /run/clone/{RUN_KEY} endpoint.
  • Clones the run identified by runKey.
  • Optionally includes execution context, model context, a tracking key, and routing options.
  • Returns a RunReadOutView object representing the cloned run.
Function signature
export async function clone(
    runKey: string,
    optionals: {
        ephemeral?: boolean;
        trackingKey?: string;
        modelContext?: ModelContext;
        executionContext?: ExecutionContext;
    } & RoutingOptions = {},
): Promise<RunReadOutView>

Parameters​

  • runKey: string - Run key for the run you want to clone.
  • optionals (Type: { ephemeral?: boolean; trackingKey?: string; modelContext?: ModelContext; executionContext?: ExecutionContext } & RoutingOptions) - (Optional) Additional clone options.
    • ephemeral?: boolean - (Optional) If true, the run will only exist so long as it is in memory. Nothing is written to the database, history, or variables.
    • trackingKey?: string - (Optional) A string that you can assign to the cloned run as a marker. You can perform a search for runs that have a specific trackingKey.
    • modelContext?: ModelContext - (Optional) Model context file overrides. Not tracked by clone operations.
    • executionContext?: ExecutionContext - (Optional) Carries arguments for model file worker on model initialization. This is tracked by clone operations.
    • RoutingOptions - Additional routing options for request handling.

Return value​

A promise resolving to a RunReadOutView object containing details of the cloned run.

Usage example​

import { runAdapter } from 'epicenter-libs';

const clonedRun = await runAdapter.clone('00000173078afb05b4ae4c726637167a1a9e');

Retrieve​

Use these methods to query the Epicenter API for runs.

Retrieve run​

The get() function retrieves a run by the run key.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a GET request to the /run/{RUN_KEY} endpoint.
  • Retrieves the run identified by the provided run key.
  • Returns a RunReadOutView object containing the run’s details.
Function signature
export async function get<
    V extends object = RunVariables,
    M extends object = RunMetadata,
>(
    runKey: string,
    optionals: RoutingOptions = {}
): Promise<RunReadOutView<V, M>>

Parameters​

  • runKey (string) – The unique key identifying the run to retrieve.
  • optionals (Type: RoutingOptions = {}) – Additional routing options.

Return value​

A promise that resolves to a RunReadOutView<V, M> object representing the requested run.

Usage example​

import { runAdapter } from 'epicenter-libs';

const run = await runAdapter.get('00000173078afb05b4ae4c726637167a1a9e');

Start run for world​

The retrieveFromWorld() function returns the run associated with the given world key. If the world's run key is null, the function creates a new run and assigns the new run key to the world.

The run gets started and loaded into memory.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a POST request to the endpoint /run/world/{WORLD_KEY}
  • Initiates a run using a provided model file and optional execution/model context.
  • Optionally applies permission locks, ephemeral state, and notification support.
  • Returns the retrieved or newly created run as a RunReadOutView object.
Function signature
export async function retrieveFromWorld(
    worldKey: string,
    model: string,
    optionals: {
        readLock?: keyof typeof ROLE;
        writeLock?: keyof typeof ROLE;
        ephemeral?: boolean;
        trackingKey?: string;
        modelContext?: ModelContext;
        executionContext?: ExecutionContext;
        allowChannel?: boolean;
    } & RoutingOptions = {},
): Promise<RunReadOutView>

Parameters​

  • worldKey (string) – The key identifying the world to retrieve the run for.
  • model (string) – Model file name to use when creating the run if it does not already exist.
  • optionals:
    • readLock?: keyof typeof ROLE - (Optional) Read lock level. Part of the permit for the run.
    • writeLock?: keyof typeof ROLE - (Optional) Write lock level. Part of the permit for the run.
    • ephemeral?: boolean - (Optional) If true, the run will only exist so long as its in memory. Nothing is written to the database, history, or variables.
    • trackingKey?: string - (Optional) A string that you can assign to a run as a marker. You can perform a search for runs that have a specific trackingKey.
    • modelContext?: ModelContext - (Optional) Model context file overrides. Not tracked by clone operations.
    • executionContext?: ExecutionContext - (Optional) Carries arguments for model file worker on model initialization. This is tracked by clone operations.
    • allowChannel?: boolean - (Optional) Opt into push notifications. Applicable to projects with phylogeny >= SILENT.
    • RoutingOptions - Additional routing options for request handling.

Return value​

A promise that resolves to a RunReadOutView.

Usage example​

import { runAdapter } from 'epicenter-libs';

// Retrieve the run for a world key, or create it if it doesn't exist
const run = await runAdapter.retrieveFromWorld(
    '0000017a445032dc38cb2cecd5fc13708314',
    'model.py',
);

Get run using strategy​

The getWithStrategy() function fetches an existing run or creates a new one, depending on the strategy provided.

tip

Provide a value for the strategy param using the RunStrategy enum.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Determines whether to fetch the run or create a new one according to the strategy argument provided.
  • To fetch runs, uses the query() function.
  • For strategies that create runs, delegates to the create() function (and therefore inherits RunCreateOptions behavior such as permits, tracking, context, etc.).
  • Throws an error if an invalid strategy is provided.
  • Returns the retrieved or newly created run as a RunReadOutView object.
Function signature
export async function getWithStrategy<
    V extends object = RunVariables,
    M extends object = RunMetadata,
>(
    strategy: RunStrategy,
    model: string,
    scope: GenericScope,
    optionals: {
        // initOperations?: Array<string | { name: string, params?: unknown[]}>,
    } & RunCreateOptions = {},
): Promise<RunReadOutView<V, M>>

Parameters​

  • strategy (RunStrategy): Determines the strategy to use.
  • model (string): The name of your model file.
  • scope (GenericScope): The scope associated of the run.
  • optionals (Type: { } & RunCreateOptions): RunCreateOptions – Options used when creating a run (permits, ephemeral, trackingKey, modelContext, executionContext, etc.).

Return value​

A promise that resolves to a RunReadOutView<V, M> containing the retrieved or newly created run.

Usage example​

import { runAdapter, SCOPE_BOUNDARY } from 'epicenter-libs';

const run = await runAdapter.getWithStrategy(
    'reuse-across-sessions',
    'model.py',
    {
        scopeBoundary: SCOPE_BOUNDARY.GROUP,
        scopeKey: '0000017dd3bf540e5ada5b1e058f08f20461',
    },
);

Filtered query​

To search for runs within a group or an episode, or for runs with a specific scope, call the query() function.

Important

This function loads model variables only from archived state. It does not restore runs to memory.

tip

When searching within a group, set the includeEpisodes parameter to true to include runs tied to specific episodes.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a GET request to one of the following endpoints:
    • /run/{SCOPE_BOUNDARY}/{SCOPE_KEY}/{MODEL}
    • /run/in/{GROUP_NAME}/{MODEL}
    • /run/in/{GROUP_NAME}/{EPISODE_NAME}/{MODEL}
  • Returns a paginated list of RunReadOutView objects.
  • When variables are requested, the response maps returned variable arrays into keyed objects for easier access.
Function signature
export async function query<
    V extends object = RunVariables,
    M extends object = RunMetadata,
>(
    model: string,
    searchOptions: {
        timeout?: number;
        variables?: (keyof V)[];
        metadata?: (keyof M)[];
        scope?: { userKey?: string } & GenericScope;
        groupName?: string;
        episodeName?: string;
        includeEpisodes?: boolean;
    } & GenericSearchOptions,
    optionals: RoutingOptions = {}
): Promise<Page<RunReadOutView<V, M>>>

Parameters​

  • model (string) – The name of your model file.
  • searchOptions (object) – Search configuration:
    • scope?: { userKey?: string } & GenericScope – (Optional) Defines the scope of the run. Can consist of GenericScope plus a userKey for user-specific scope.
      • scopeBoundary – Defines the type of scope.
      • scopeKey – Unique identifier tied to the scope.
      • userKey? – When provided, automatically filters results to that user.
    • groupName?: string – (Optional) Search within a specific group.
    • episodeName?: string – (Optional) Search within a specific episode.
    • includeEpisodes?: boolean – (Optional) When searching within a group, include runs tied to specific episodes. Default is false.
    • variables?: (keyof V)[] – (Optional) List of variables to include with the runs found.
    • metadata?: (keyof M)[] – (Optional) List of metadata to include with the runs found.
    • timeout?: number – (Optional) Number of seconds to wait for the server response.
    • GenericSearchOptions – Additional search options including:
      • filter
      • sort
      • first
      • max (maximum 200 results per request)
  • optionals (Type: RoutingOptions = {}) – Additional routing options.

Return value​

A promise resolving to a Page<RunReadOutView<V, M>>, containing:

  • A paginated list of matching runs
  • Included variables and metadata (if requested)
  • Pagination metadata

Usage example​

import { runAdapter, SCOPE_BOUNDARY } from 'epicenter-libs';

const page = await runAdapter.query('model.xlsx', {
    scope: {
        scopeBoundary: SCOPE_BOUNDARY.GROUP,
        scopeKey: '0000017dd3bf540e5ada5b1e058f08f20461'
    },
    filter: [
        'var.score>=24',
        'run.hidden=false'
    ],
    sort: ['+run.created'],
    variables: ['score'],
    metadata: ['classification'],
    max: 50
});

Update​

Update run​

Update a run.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a PATCH request to the /run/{RUN_KEY} endpoint when updating a single run.
  • Uses PATCH /run with runKey as a query parameter when updating multiple runs.
  • Automatically builds a permit object when readLock or writeLock is provided.
  • Returns a RunReadOutView object representing the updated run.
Function signature
export async function update(
    runKey: string | string[],
    update: {
        readLock?: keyof typeof ROLE;
        writeLock?: keyof typeof ROLE;
        trackingKey?: string;
        marked?: boolean;
        hidden?: boolean;
        closed?: boolean;
        allowChannel?: boolean;
    },
    optionals: RoutingOptions = {},
): Promise<RunReadOutView>

Parameters​

  • runKey (string | string[]) – The key (or keys) identifying the run(s) to update.
  • update (Type: { readLock?: keyof typeof ROLE; writeLock?: keyof typeof ROLE; trackingKey?: string; marked?: boolean; hidden?: boolean; closed?: boolean; allowChannel?: boolean }) – Object containing run attributes to update.
    • readLock?: keyof typeof ROLE – (Optional) Read lock level. Part of the permit for the run.
    • writeLock?: keyof typeof ROLE – (Optional) Write lock level. Part of the permit for the run.
    • trackingKey (string) – (Optional) A string that you can assign to a run as a marker.
    • marked (boolean) – (Optional) Equivalent to the “saved” flag in v2.
    • hidden (boolean) – (Optional) Equivalent to the “trashed” flag in v2.
    • closed (boolean) – (Optional) Marks the run as closed, meaning it will not be restored again.
    • allowChannel (boolean) – (Optional) Opt into push notifications. Applicable to projects with phylogeny >= SILENT.
  • optionals (Type: RoutingOptions = {}) – Additional routing options for request handling.

Return value​

A promise that resolves to a RunReadOutView object containing details of the updated run.

Usage example​

import { runAdapter } from 'epicenter-libs';

const updatedRun = await runAdapter.update(
    '00000173078afb05b4ae4c726637167a1a9e',
    {
        readLock: 'FACILITATOR',
        writeLock: 'FACILITATOR',
        marked: true,
        hidden: false,
    }
);

Manage​

Restore run​

Call the restore() function to restore an existing run into memory.

Restoring a run loads its saved state so it can resume execution. You can optionally override the model and execution context when restoring.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a POST request to the /run/restore/{RUN_KEY} endpoint.
  • Restores the run identified by runKey into memory.
  • Optionally includes execution context, model context overrides, and routing options.
  • Returns a RunReadOutView object representing the restored run.
Function signature
export async function restore(
    runKey: string,
    optionals: {
        ephemeral?: boolean;
        modelContext?: ModelContext;
        executionContext?: ExecutionContext;
    } & RoutingOptions = {},
): Promise<RunReadOutView>

Parameters​

  • runKey: string - Run key for the run you want to restore.
  • optionals (Type: { ephemeral?: boolean; modelContext?: ModelContext; executionContext?: ExecutionContext } & RoutingOptions) - (Optional) Additional restore options.
    • ephemeral?: boolean - (Optional) If true, the run will only exist so long as it is in memory. Nothing is written to the database, history, or variables.
    • modelContext?: ModelContext - (Optional) Model context file overrides. Not tracked by clone operations.
    • executionContext?: ExecutionContext - (Optional) Carries arguments for model file worker on model initialization. This is tracked by clone operations.
    • RoutingOptions - Additional routing options for request handling.

Return value​

A promise resolving to a RunReadOutView object containing details of the restored run.

Usage example​

import { runAdapter } from 'epicenter-libs';

const restoredRun = await runAdapter.restore('00000173078afb05b4ae4c726637167a1a9e');

Rewind run​

The rewind() function stops the run, re-starts it, and replays it to a specified point.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a POST request to the /run/rewind/{RUN_KEY} endpoint.
  • Sends the number of steps to rewind as rewindCount in the request body.
  • Optionally includes ephemeral and model context overrides.
  • Returns a RunReadOutView object representing the rewound run.
Function signature
export async function rewind(
    runKey: string,
    steps: number,
    optionals: {
        ephemeral?: boolean,
        modelContext?: ModelContext,
    } & RoutingOptions = {}
): Promise<RunReadOutView>

Parameters​

  • runKey (string) – The run key identifying the run to rewind.
  • steps (number) – The number of steps to rewind the run.
  • optionals (Type: { ephemeral?: boolean; modelContext?: ModelContext } & RoutingOptions):
    • ephemeral? (boolean) – (Optional) If true, the run will only exist so long as it is in memory. Nothing is written to the database, history, or variables.
    • modelContext?: ModelContext – (Optional) .ctx2 file overrides. Not tracked by clone operations.
    • RoutingOptions – Additional routing options for request handling.

Return value​

A promise that resolves to a RunReadOutView object containing details of the rewound run.

Usage example​

import { runAdapter } from 'epicenter-libs';

const rewoundRun = await runAdapter.rewind(
    '00000173078afb05b4ae4c726637167a1a9e',
    5
);

The migrate() function copies a run to a different episode.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

  • Constructs a POST request to the endpoint /run/migrate/to/{EPISODE_KEY}/{RUN_KEY}.
  • Returns the migrated run.
Function signature
export async function migrate<
    V extends object = RunVariables,
    M extends object = RunMetadata,
>(
    runKey: string,
    episodeKey: string,
    optionals: {
        ephemeral?: boolean;
        trackingKey?: string;
        modelContext?: ModelContext;
        executionContext?: ExecutionContext;
    } & RoutingOptions = {},
): Promise<RunReadOutView<V, M>>

Parameters​

  • runKey (string): The run key for the run you want to copy and migrate.
  • episodeKey (string): The key of the episode to which the run is being migrated.
  • optionals: Optional parameters that can include:
    • ephemeral (boolean) - If true, the run will only exist so long as its in memory. Nothing is written to the database, history, or variables.
    • trackingKey (string) - A string that you can assign to a run as a marker. You can perform a search for runs that have a specific trackingKey.
    • modelContext (ModelContext) - Model context file overrides. Not tracked by clone operations.
    • executionContext (ExecutionContext) - Carries arguments for model file worker on model initialization. This is tracked by migrate operations.
    • RoutingOptions: Additional routing options.

Return value​

A promise that resolves to a RunReadOutView<V, M> containing the migrated run.

Usage example​

import { runAdapter } from 'epicenter-libs';

const migratedRun = await runAdapter.migrate(
    '00000173078afb05b4ae4c726637167a1a9e',
    '0000017dd3bf540e5ada5b1e058f08f20461',
);

Delete​

Delete run​

The remove() function does not actually delete the run. The run is instead removed from memory. The function can be used as a means of preserving server CPUs, and should be used when you do not expect to perform any additional actions that would bring the run back into memory.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a DELETE request to the endpoint /run/{runKey}.
  • Sends the runKey as part of the request URL.
  • Executes the request and returns a void promise upon success.
Function signature
export async function remove(
    runKey: string,
    optionals: RoutingOptions = {}
): Promise<void>

Parameters​

  • runKey (string): The run key identifying the run to be deleted.
  • optionals (Type: RoutingOptions = {}): Additional routing options.

Return value​

A promise that resolves to void when the run is successfully deleted.

Usage example​

import { runAdapter } from 'epicenter-libs';  

runAdapter.remove('0000017a445032dc38cb2cecd5fc13563218');

Delete run for world​

The removeFromWorld() function closes the run and removes it from memory. It also sets the runKey in the specified world to null.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Sends a DELETE request to the /run/world/{worldKey} endpoint.
  • Returns a void promise upon successful deletion.
Function signature
export async function removeFromWorld(
    worldKey: string,
    optionals: RoutingOptions = {},
): Promise<void>

Parameters​

Return value​

A promise that resolves to void when successful.

Usage example​

import { runAdapter } from 'epicenter-libs';

await runAdapter.removeFromWorld('0000017a445032dc38cb2cecd5fc13765987');

Singular runs​

Create singular run​

The createSingular() function creates a singular run, if one does not yet exist.

If a singular run already exists in the project, the function returns the existing one.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a POST request to the /run/singular endpoint.
  • Creates a project-scoped run using the specified model file.
  • Optionally includes permissions, execution context, model context overrides, and routing options.
  • Returns a RunReadOutView object representing the newly created run.
Function signature
export async function createSingular<
    V extends object = RunVariables,
    M extends object = RunMetadata,
>(
    model: string,
    optionals: RunCreateOptions = {},
): Promise<RunReadOutView<V, M>>

Parameters​

Return value​

A promise resolving to a RunReadOutView object containing details of the newly created run.

Usage example​

import { runAdapter } from 'epicenter-libs';

await runAdapter.createSingular('model.py');

Get singular run key​

The getSingularRunKey() returns the unique runKey for the project's singular run.

Permissions​

Requires a role of ANONYMOUS or higher.

Function description​

  • Constructs a GET request to the /run/singular/key endpoint.
  • Returns the runKey associated with the project’s singular run.
Function signature
export async function getSingularRunKey(
    optionals: RoutingOptions = {}
): Promise<number>

Parameters​

Return value​

  • Type: Promise<number>
  • Description: A promise resolving to the singular run key.

Usage example​

import { runAdapter } from 'epicenter-libs';

runAdapter.getSingularRunKey();

Variables​

Get variables from a run​

The getVariables() function retrieves the current values of specified variables from one or more runs.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a POST request to:
    • /run/variable/{RUN_KEY} for a single run
    • /run/variable for multiple runs
  • Sends the requested variable names using the include parameter.
  • Supports optional timeout, ritual, and ignorable flags.
  • When multiple runKey values are provided, the response returns an array of { runKey, variables } objects.
  • When a single runKey is provided, the response returns a key-value object of the requested variables.
  • When runKey is an array, only the EXORCISE ritual is permitted.
Function signature
export async function getVariables<V extends object = RunVariables>(
    runKey: string | string[],
    variables: (keyof V)[],
    optionals: {
        timeout?: number;
        ritual?: keyof typeof RITUAL;
        ignorable?: boolean;
    } & RoutingOptions = {},
): Promise<
    | Pick<V, keyof V>
    | { runKey: string; variables: Pick<V, keyof V> }[]
>

Parameters​

  • runKey (string | string[]) – Identifier for your run or runs.
  • variables ((keyof V)[]) – List of variable names to retrieve.
  • optionals (Type: { timeout?: number; ritual?: keyof typeof RITUAL; ignorable?: boolean } & RoutingOptions):
    • timeout? (number) – Number of seconds to wait for the server response.
    • ritual?: keyof typeof RITUAL – Ritual describing how to store and remove the run from memory. When runKey is an array, only the EXORCISE ritual is permitted.
    • ignorable? (boolean) – If true, suppresses errors when variables are not found.
    • RoutingOptions – Additional routing options.

Return value​

A promise that resolves to:

  • If runKey is a single string, a Pick<V, keyof V> object mapping variable names to their values.
  • If runKey is an array, an array of objects with the shape: 
    {
        runKey: string;
        variables: Pick<V, keyof V>;
    }

Usage example​

import { runAdapter } from 'epicenter-libs';

// Single run
const vars = await runAdapter.getVariables(
    '00000173078afb05b4ae4c726637167a1a9e',
    ['score', 'status']
);

// Multiple runs
const varsArray = await runAdapter.getVariables(
    [
        '00000173078afb05b4ae4c726637167a1a9e',
        '0000017dd3bf540e5ada5b1e058f08f20461'
    ],
    ['score', 'status']
);

Retrieve a run variable​

The getVariable() function retrieves one or more model variables for one or more runs.

This is a convenience wrapper around getVariables():

  • If a single runKey and single variable are provided, the function performs a GET request.
  • If multiple run keys or multiple variables are provided, the function delegates to getVariables() and performs a POST request.

Permissions​

Requires a role of ANONYMOUS or higher.

Function description​

  • Constructs a GET request to /run/variable/{RUN_KEY}/{VARIABLE} when retrieving a single variable from a single run.
  • Delegates to getVariables() when retrieving multiple variables or targeting multiple runs.
  • Supports optional timeout and ritual parameters.
  • Returns:
    • A single variable value (single run + single variable)
    • A keyed object of variables (single run + multiple variables)
    • An array of { runKey, variables } objects (multiple runs)
Function signature
export async function getVariable<V extends object = RunVariables>(
    runKey: string | string[],
    variable: keyof V | (keyof V)[],
    optionals: {
        timeout?: number;
        ritual?: keyof typeof RITUAL;
    } & RoutingOptions = {},
): Promise<
    | V[keyof V]
    | Pick<V, keyof V>
    | { runKey: string; variables: Pick<V, keyof V> }[]
>

Parameters​

  • runKey (string | string[]) – Key (or list of keys) for the run(s) to retrieve the variable(s) from.
  • variable (keyof V | (keyof V)[]) – Variable name or list of variable names to retrieve.
  • optionals (Type: { timeout?: number; ritual?: keyof typeof RITUAL } & RoutingOptions):

Return value​

A promise that resolves to one of the following:

  • If runKey is a single string and variable is a single key: The value of the requested variable (V[keyof V]).
  • If runKey is a single string and variable is an array: A Pick<V, keyof V> object mapping variable names to their values.
  • If runKey is an array: An array of objects with the shape: 
    {
        runKey: string;
        variables: Pick<V, keyof V>;
    }

Usage example​

import { runAdapter } from 'epicenter-libs';

// Single runKey, single variable
const value = await runAdapter.getVariable(
    '00000173078afb05b4ae4c726637167a1a9e',
    'score'
);

// Multiple runKeys, multiple variables
const varsArray = await runAdapter.getVariable(
    [
        '00000173078afb05b4ae4c726637167a1a9e',
        '0000017dd3bf540e5ada5b1e058f08f20461'
    ],
    ['score', 'status']
);

Update run variables​

The updateVariables() function updates model variables for one or more runs.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a PATCH request to:
    • /run/variable/{RUN_KEY} when updating a single run
    • /run/variable when updating multiple runs
  • Sends updated variable values in the request body.
  • Supports optional timeout and ritual parameters.
  • When runKey is an array, only the EXORCISE ritual is permitted.
  • Returns an object containing the updated variable names and their new values.
Function signature
export async function updateVariables<V extends object = RunVariables>(
    runKey: string | string[],
    update: Partial<V>,
    optionals: {
        timeout?: number;
        ritual?: keyof typeof RITUAL;
    } & RoutingOptions = {},
): Promise<Partial<V>>

Parameters​

  • runKey (string | string[]) – A single run key or an array of run keys indicating which run(s) to update.
  • update (Partial<V>) – An object mapping variable names to their updated values.
  • optionals (Type: { timeout?: number; ritual?: keyof typeof RITUAL } & RoutingOptions):
    • timeout? (number) – Number of seconds to wait for the server response.
    • ritual?: keyof typeof RITUAL – Specifies the ritual to follow when updating. When runKey is an array, only the EXORCISE ritual is permitted.
    • RoutingOptions – Additional routing options.

Return value​

A promise that resolves to a Partial<V> object containing the variables that were updated and their new values.

Usage example​

import { runAdapter } from 'epicenter-libs';

const updated = await runAdapter.updateVariables(
    '00000173078afb05b4ae4c726637167a1a9e',
    {
        price: 100,
        foo: 'bar',
    }
);

Operations​

Execute operation​

Use the operation() function to execute a named operation on a run.

Permissions​

Requires a role of ANONYMOUS or higher.

Function description​

  • Constructs a POST request to the /run/operation endpoint.
  • Provides the run key, operation name, and arguments.
  • Supplies optional arguments, including timeout and ritual.
  • Can target one or multiple runs, though certain rituals like EXORCISE must be used when calling across multiple runs.
Function signature
export async function operation(
    runKey: string | string[],
    name: string,           // Operation name
    args: unknown[] = [],   // Operation arguments
    optionals: {
        timeout?: number,
        ritual?: keyof typeof RITUAL,
    } & RoutingOptions = {}
): Promise<unknown>

Parameters​

  • runKey: string | string[] – The run identifier or a list of run identifiers the operation should be applied to.
  • name: string – The name of the operation to execute inside the model run.
  • args: unknown[] = [] – (Optional) Arguments to pass to the operation.
  • optionals – (Optional) Additional routing and execution control options:
    • timeout?: number – (Optional) Maximum duration (in ms) to wait for a response.
    • ritual?: keyof typeof RITUAL – (Optional) The ritual that determines how the run is revived or restored from memory/archive.
    • RoutingOptions – Additional routing and request handling options.

Return value​

A promise resolving to the result of the executed operation.

Usage example​

import { runAdapter, RITUAL } from 'epicenter-libs';

const result = await runAdapter.operation(
    '0000019975d0kdvso160de2450566846kr45',
    'calculatePrice',
    [42, 'premium'],
    { ritual: RITUAL.REANIMATE, timeout: 5000 }
);

console.log(result);

Trigger actions​

The action() function executes one or more actions on one or more runs.

Permissions​

Requires a role of ANONYMOUS or higher.

Function description​

  • Constructs a POST request to:
    • /run/action/{RUN_KEY} when executing actions on a single run
    • /run/action when executing actions on multiple runs
  • Supports action types such as set and execute (depending on the provided Actionable definitions).
  • Supports an optional ritual parameter. If multiple runKey values are provided, the EXORCISE ritual is used.
  • Returns an object containing the action results.
Function signature
export async function action(
    runKey: string | string[],
    actionList: Actionable[],
    optionals: {
        timeout?: number;
        ritual?: keyof typeof RITUAL;
    } & RoutingOptions = {},
): Promise<Record<string, unknown>>

Parameters​

  • runKey (string | string[]) – A single run key or an array of run keys.
  • actionList (Actionable[]) – A list of actions to perform.
    • name (string) – The name of the variable or method to act upon.
    • value? (unknown) – The value to assign (for set actions).
    • arguments? (unknown[]) – Arguments to pass (for execute actions).
    • objectType (string) – The type of action (for example, set or execute).
  • optionals (Type: { timeout?: number; ritual?: keyof typeof RITUAL } & RoutingOptions):
    • timeout? (number) – Number of seconds to wait for the server response.
    • ritual? (keyof typeof RITUAL) – Ritual describing how to store and remove the run from memory.
    • RoutingOptions = {} – Additional routing options.

Return value​

A promise that resolves to a Record<string, unknown> object containing the results of the executed actions.

Usage example​

import { runAdapter } from 'epicenter-libs';

const actions = [
    { name: 'price', value: 100, objectType: 'set' },
    { name: 'simulate', arguments: [10], objectType: 'execute' },
];

// Execute actions on a single run
const result = await runAdapter.action(
    '00000173078afb05b4ae4c726637167a1a9e',
    actions,
);

// Execute actions on multiple runs
const results = await runAdapter.action(
    [
        '00000173078afb05b4ae4c726637167a1a9e',
        '0000017dd3bf540e5ada5b1e058f08f20461',
    ],
    actions,
);

Metadata​

Get run metadata​

The getMetadata() function retrieves metadata for one or more runs.

Note

The function uses a POST request rather than GET.

Permissions​

Requires a role of ANONYMOUS or higher.

Function description​

  • Constructs a POST request to the /run/meta endpoint.
  • Sends the requested metadata keys using the include parameter.
  • Accepts a single runKey or an array of run keys.
  • When multiple run keys are provided, returns an array of { runKey, data } objects.
  • When a single run key is provided, returns an object containing the requested metadata key-value pairs.
Function signature
export async function getMetadata<M extends object = RunMetadata>(
    runKey: string | string[],
    metadata: (keyof M)[],
    optionals: {
        timeout?: number;
    } & RoutingOptions = {},
): Promise<
    | Pick<M, keyof M>
    | { runKey: string; data: Pick<M, keyof M> }[]
>

Parameters​

  • runKey (string | string[]) – A single run key or an array of run keys for which metadata is requested.
  • metadata ((keyof M)[]) – List of metadata keys to retrieve (typed to the generic metadata shape M).
  • optionals (Type: { timeout?: number } & RoutingOptions):
    • timeout? (number) – Number of seconds to wait for the server response.
    • RoutingOptions – Additional routing options.

Return value​

A promise that resolves to one of the following:

  • If runKey is a single string, a Pick<M, keyof M> object containing the requested metadata key-value pairs.
  • If runKey is an array, an array of objects with the shape: 
    {
        runKey: string;
        data: Pick<M, keyof M>;
    }

Usage example​

import { runAdapter } from 'epicenter-libs';

// Single run
const meta = await runAdapter.getMetadata(
    '00000173078afb05b4ae4c726637167a1a9e',
    ['meta1', 'meta2']
);

// Multiple runs
const metaArray = await runAdapter.getMetadata(
    [
        '00000173078afb05b4ae4c726637167a1a9e',
        '0000017dd3bf540e5ada5b1e058f08f20461'
    ],
    ['meta1', 'meta2']
);

Update run metadata​

The updateMetadata() function updates metadata for one or more runs.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a PATCH request to:
    • /run/meta/{RUN_KEY} when updating a single run
    • /run/meta when updating multiple runs
  • When runKey is an array, the runKey values are sent as query parameters.
  • Sends metadata update operations in the request body.
  • Supports set, push, and pop update operations.
  • Returns an object containing the updated metadata.
Function signature
export async function updateMetadata<M extends object = RunMetadata>(
    runKey: string | string[],
    update: MetadataUpdate<M>,
    optionals: {
        timeout?: number;
    } & RoutingOptions = {},
): Promise<Partial<M>>

Parameters​

  • runKey (string | string[]) – A single run key or an array of run keys indicating which run(s) to update.
  • update (MetadataUpdate<M>) – Metadata update operations.
    • set? (Partial<M>) – Key-value pairs to set in the metadata.
    • push? (Partial<M>) – Key-value pairs to push to array metadata.
    • pop? (Partial<Record<keyof M, MetadataPop>>) – Keys with pop operations (first, last, or all) to remove from array metadata.
  • optionals (Type: { timeout?: number } & RoutingOptions):
    • timeout? (number) – Number of seconds to wait for the server response.
    • RoutingOptions – Additional routing options.

Return value​

A promise that resolves to a Partial<M> object containing the updated metadata.

Usage example​

import { runAdapter } from 'epicenter-libs';

// Set metadata values
const updated = await runAdapter.updateMetadata('00000173078afb05b4ae4c726637167a1a9e', {
    set: {
        classification: 'new-classification',
        categorization: 'new-categorization',
    },
});

// Push values to array metadata
const pushed = await runAdapter.updateMetadata('00000173078afb05b4ae4c726637167a1a9e', {
    push: {
        history: 'new-entry',
    },
});

// Pop values from array metadata
const popped = await runAdapter.updateMetadata('00000173078afb05b4ae4c726637167a1a9e', {
    pop: {
        history: { objectType: 'last' },
    },
});

Introspect​

The introspect functions return metadata for a model or for a specific model run.

Introspect model​

Use the introspect() function to retrieve metadata about a specific model.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Sends a GET request to introspect a model, providing the model file name as a path parameter.
  • Returns the API response in a Result object.
Function signature
export async function introspect(
    model: string,
    optionals: RoutingOptions = {}
): Promise<Record<string, unknown>>

Parameters​

  • model: string – The name or path of the model file to introspect.
  • optionals: RoutingOptions = {} – (Optional) Additional routing and request handling options. See RoutingOptions for details.

Return value​

A promise resolving to a Record<string, unknown> containing the introspected metadata associated with the given model file.

Usage example​

import { runAdapter } from 'epicenter-libs';

const modelInfo = await runAdapter.introspect('pricing-model.py');

console.log(modelInfo);

Introspect run​

Use the introspectWithRunKey() function to retrieve metadata for a specific model run.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Sends a GET request to introspect a run, providing a runKey as a path parameter.
  • Returns the API response in a Result object.
Function signature
export async function introspectWithRunKey(
    runKey: string,
    optionals: RoutingOptions = {}
): Promise<Record<string, unknown>>

Parameters​

  • runKey: string – The unique identifier for the run to be introspected.
  • optionals: RoutingOptions = {} – (Optional) Additional routing and request handling options. See RoutingOptions for details.

Return value​

A promise resolving to a Record<string, unknown> containing the introspected model metadata associated with the given run.

Usage example​

import { runAdapter } from 'epicenter-libs';

const modelInfo = await runAdapter.introspectWithRunKey('abc123');
console.log(modelInfo);