> ## Documentation Index
> Fetch the complete documentation index at: https://doc.lucidworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Async Prediction API

export const LwTemplate = ({title = "Key questions to get you started", icon = "sparkles", cta = "Powered by Agent Studio", linkHref = "https://lucidworks.com/demo/?utm_source=docs&utm_medium=referral&utm_campaign=docs_cta_ai"}) => {
  const [isLoaded, setIsLoaded] = useState(false);
  useEffect(() => {
    const timer = setTimeout(() => {
      setIsLoaded(true);
    }, 500);
    return () => clearTimeout(timer);
  }, []);
  return <div className="lw-template-container">
      <Card title={title} icon={icon}>
        {isLoaded && <span dangerouslySetInnerHTML={{
    __html: `<lw-template id="a029c1a9-28be-427e-b0e1-5d918920246a"></lw-template
            >`
  }} />}
        <Link href={linkHref} className="agent-studio-link text-left text-gray-600 gap-2 dark:text-gray-400 text-sm font-medium flex flex-row items-center hover:text-primary dark:hover:text-primary-light group-hover:text-primary group-hover:dark:text-primary-light">Powered by Lucidworks Agent Studio</Link>
      </Card>
    </div>;
};

[old doc.lw link]: https://doc.lucidworks.com/lw-platform/ai/55ug0f

[localhost link]: http://localhost:3000/docs/lw-platform/lw-ai/lw-ai-apis/lw-ai-async-prediction-api/overview

[mintlify link]: https://doc.lucidworks.com/docs/lw-platform/lw-ai/lw-ai-apis/lw-ai-async-prediction-api/overview

The Lucidworks AI Async Prediction API is used to send asynchronous API calls that run predictions on specific models.

The Lucidworks AI Async Prediction API contains two requests:

* POST request - submits a prediction task for a specific `useCase` and `modelId`. The API responds with the following information:

* `predictionId`. A unique UUID for the submitted prediction task that can be used later to retrieve the results.

* `status`. The current state of the prediction task.
  * GET request - uses the `predictionId` you submit from a previously-submitted POST request and returns the results associated with that previous request.
  {/* // end::common-request[] */}

The LWAI Async Prediction API supports models hosted by Lucidworks and specific third-party models. The [Lucidworks AI Use Case API](/docs/lw-platform/lw-ai/lw-ai-apis/lw-ai-use-case-api) returns a list of all supported models. For more information about supported models, see [Generative AI models](/docs/lw-platform/lw-ai/lw-ai-generative-ai#generative-ai-models).

You can enter the values returned in the Lucidworks AI Use Case API for the `USE_CASE` and `MODEL_ID` fields in the `/async-prediction` use case POST requests.

The generic path for the Async Prediction API is [`/ai/async-prediction/USE_CASE/MODEL_ID`](#async-prediction-use-case-by-modelid).

<Note>
  For detailed API specifications in Swagger/OpenAPI format, see [Platform APIs](/api-reference/get-predictions/model-predictions-by-use-case).
</Note>

<LwTemplate />

## Prerequisites

<Note>
  This section describes the prerequisites if your organization generates and manages the authentication and API keys. If your organization has opted to contract with Lucidworks to provide the API keys to execute generative AI (Gen-AI) models, see [Generative AI using Lucidworks-managed keys](/docs/lw-platform/lw-ai/lw-ai-generative-ai-using-lw-keys).
</Note>

To use this API, you need:

* The unique `APPLICATION_ID` for your Lucidworks AI application, which is provided by Lucidworks.
* A bearer token generated with a scope value of `machinelearning.predict`. For more information, see [Authentication API](/docs/lw-platform/lw-platform/authentication-api).
* Other required fields specified in each individual use case.

## Common POST request parameters and fields

Some parameters in the `/ai/async-prediction/USE_CASE/MODEL_ID` POST request are common to all of the generative AI (Gen-AI) use cases, such as the `modelConfig` parameter.
Also referred to as hyperparameters, these fields set certain controls on the response.
Refer to the [API spec](/api-reference/get-predictions/model-predictions-by-use-case) for more information.

## Async prediction use case by modelid

The `/ai/async-prediction/USE_CASE/MODEL_ID` request submits a prediction task for a specific `useCase` and `modelId`. Upon submission, a successful response includes a unique `predictionId` and a `status`. The `predictionId` can be used later in the GET request to retrieve the results.

<Check>Unique fields and values in the request are described in each [use case](#async-prediction-use-case-by-modelid).</Check>

### Example POST request

<CodeGroup>
  ```json wrap expandable Request theme={"dark"}
  curl --request POST \
    --url https://APPLICATION_ID.applications.lucidworks.com/ai/async-prediction/USE_CASE/MODEL_ID \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer ACCESS_TOKEN'
    --data '{
    "batch": [
      {
        "text": "Content for the model to analyze."
      }
    ],
    "useCaseConfig": [
      {
        "useSystemPrompt": true
      }
    ],
    "modelConfig": [
      {
        "temperature": 0.8,
        "topP": 1,
        "presencePenalty": 2,
        "frequencyPenalty": 1,
        "maxTokens": 1
      }
    ]
  }'
  ```

  ```json wrap Success theme={"dark"}
  {
  	"predictionId": "fd110486-f168-47c0-a419-1518a4840589",
  	"status": "SUBMITTED"
  }
  ```

  ```json wrap Error theme={"dark"}
  {
  	"predictionId": "fd110486-f168-47c0-a419-1518a4840589",
  	"status": "ERROR",
  	"message": "System prompt exceeded the maximum number of allowed input tokens: 81 vs -1091798"
  }
  ```
</CodeGroup>

### Example GET request

```bash wrap theme={"dark"}
curl --request GET
--url https://APPLICATION_ID.applications.lucidworks.com/ai/async-prediction/PREDICTION_ID
--header 'Authorization: Bearer Auth '
```

The response varies based on the specific use case and the fields included in the request.