Creating runs via the API

​

Overview

After registering your functions using the Inferable the 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. A message 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 '{
  "message": "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 Result Handlers for details on an asynchronous alternative for receiving Run results.

​

4. Understanding run Results

Assuming the run satus is success the run will return either a structured result and/or a summary message.

​

Structured Result Example

{
  "run": {
    "id": "01J8GNNHRRZA9E605BEM57A3HT",
    "name": "Inventory status",
    "status": "done",
    "summary": "I found the following items",
    "result": [
      {
        "name": "Sonic Screwdriver",
        "qty": 10
      },
      {
        "name": "Towel",
        "qty": 5
      }
      // ... more items ...
    ]
    // ... other run metadata ...
  },
  "jobs": [
    {
      "id": "01J8GNNQ04SVQ7HAJQ7HMQ7M6W",
      "status": "success",
      "targetFn": "searchInventory",
      "service": "example",
      "resultType": "resolution",
      "createdAt": "1970-01-01T00:00:00.000Z"
    }
  ],
  "inputRequests": []
}

​

Summary Result

If a run fails to produce a structured result, the result field will be null:

{
  "run": {
    // ... run metadata ...
    "status": "success",
    "result": null,
    "summary": "Unable to process inventory data"
  }
  // ... other fields ...
}

​

Failure Result Example

A run will be marked as failed only if something prevented the run from running. A common example of this is if no function are available. Individual function failures, or the inability to satisfy the result object schema are not considered failures.

{
  "run": {
    // ... run metadata ...
    "status": "failed",
    "failureReason": "No tools found, which means no services are available to execute this function. At least one service must be available.",
    "result": null,
    "summary": "null"
  }
  // ... other fields ...
}

​

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.