Creating runs via the API
Learn how to create runs, retrieve results, and handle responses using the Inferable 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:
Your cluster may already have a sk_machine....
key.
However, this key does not have the ability to create new Runs.
Please see Authentication for different key types.
For more details see API Authentication
2. Create a run
To create a run, you need to provide two key inputs:
- A message describing the task for the run (e.g., “What does our inventory look like?“)
- The schema for the expected result
Here’s an example API request to create a run:
Response
Upon successful creation, you’ll receive a run ID:
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:
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:
Status | Description |
---|---|
pending | The Run has been created but not yet started processing. |
running | The Run is currently processing. |
paused | The Run is paused (e.g., waiting for an input request). |
done | The Run has completed. |
failed | The Run failed. Please see failureReason for more information. |
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
Summary Result
If a run fails to produce a structured result, the result
field will be null
:
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.
Best Practices
- Error Handling: Always check the
status
field to ensure the run completed successfully. - Polling Interval: When checking for results, implement a reasonable polling interval to stay within rate limits.
- Timeout Handling: Set a maximum wait time for long-running runs to prevent indefinite waiting.
Was this page helpful?