Creating runs via the API

const run = await inferable.run({
  initialPrompt: `Submit a support ticket with these details: ${details}`,
  attachedFunctions: [
    {
      function: "submitTicket",
      service: "default",
    },
    {
      function: "sendEmail",
      service: "default",
    },
    // ... Any other functions to make available to the run
  ],
  resultSchema: z.object({
    success: z.boolean(),
  }),
  // Optional: Subscribe an Inferable function to receive notifications when the run status changes
  // onStatusChange: { function: { function: "handler", service: "default" } },
});

​

Overview

After registering your functions using the Inferable SDK, you can create Runs by issuing prompts to Inferable.

This guide will walk you through the process of creating a Run via the API and retrieving structured results.

​

1. Obtain a Cluster Consumer Key

Before creating a Run, you need a cluster consumer key. If you haven’t created one yet, use the following CLI command:

inf auth keys create --type=cluster_consume my_runs_key

For more details see API Authentication

​

2. Create a run

To create a run, you need to provide two key inputs:

1. An initial prompt describing the task for the run (e.g., “What does our inventory look like?“)
2. The schema for the expected result

Here’s an example API request to create a run:

curl --request POST \
  --url https://api.inferable.ai/clusters/{clusterId}/runs \
  --header 'Content-Type: application/json' \
  --header 'authorization: <cluster_consumer_key>' \
  --data '{
  "initialPrompt": "What does our inventory look like?",
  "result": {
    "schema": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "qty": { "type": "number" }
        }
      }
    }
  }
}'

​

Response

Upon successful creation, you’ll receive a run ID:

{
  "id": "wf_123"
}

The run will start executing in the background, with the control plane determining which services to invoke and in what order.

​

3. Retrieve run Results

To get the results of your run, poll the following endpoint using the run ID:

curl --request GET \
  --url https://api.inferable.ai/clusters/{clusterId}/runs/{runId} \
  --header 'authorization: <cluster_consumer_key>'

The /clusters/{clusterId}/runs/{runId} endpoint will return details for a single run, including its status and result (if available).

A run may take some time to complete. You can inspect the status to determine if it is finished:

Please see OnStatusChange for details on an asynchronous alternative for receiving Run results.

See Run Results for details on result structure.

​

Best Practices

1. Error Handling: Always check the status field to ensure the run completed successfully.
2. Polling Interval: When checking for results, implement a reasonable polling interval to stay within rate limits.
3. Timeout Handling: Set a maximum wait time for long-running runs to prevent indefinite waiting.