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

# Run Inference

> Send input features to a deployed model and receive a prediction. The model container must be in ACTIVE status.

### Authentication

Pass your `imp_` API key as a Bearer token:

```
Authorization: Bearer imp_your_key_here
```

Your `user_id` is resolved server-side from the key — do not include it in the request body.

### Request body

<ParamField body="deployment_id" type="string" required>
  The ID of the deployed model to call. Find this on the **Models** page in the dashboard.

  Example: `clf-titanic-survived`
</ParamField>

<ParamField body="inputs" type="object" required>
  A JSON object mapping feature column names to their values, exactly as they appear in the training dataset.

  ```json theme={null}
  {
    "Pclass": 3,
    "Sex": "male",
    "Age": 22,
    "Fare": 7.25
  }
  ```
</ParamField>

### Response

<ResponseField name="prediction" type="any">
  The model's output. For classification models this is the predicted class label (e.g. `0` or `"yes"`). For regression models it is a numeric value.
</ResponseField>

<ResponseField name="probability" type="number | null">
  Confidence score between `0` and `1` for the predicted class. Present for classification models, `null` for regression.
</ResponseField>

<ResponseField name="target" type="string | null">
  The name of the target column the model was trained to predict.
</ResponseField>

### Rate limit headers

Every response includes standard rate-limit headers:

| Header                  | Description                                      |
| ----------------------- | ------------------------------------------------ |
| `X-RateLimit-Limit`     | Requests allowed in the current 60-second window |
| `X-RateLimit-Remaining` | Requests remaining in the current window         |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets            |
| `Retry-After`           | Seconds to wait before retrying (only on `429`)  |

<RequestExample>
  ```bash cURL — Titanic survival prediction theme={null}
  curl -s -X POST "https://inference.impulselabs.ai/infer" \
    -H "Authorization: Bearer $IMPULSE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "deployment_id": "clf-titanic-survived",
      "inputs": {
        "Pclass": 3,
        "Sex": "male",
        "Age": 22,
        "SibSp": 1,
        "Parch": 0,
        "Fare": 7.25,
        "Embarked": "S"
      }
    }'
  ```

  ```bash cURL — Customer churn prediction theme={null}
  curl -s -X POST "https://inference.impulselabs.ai/infer" \
    -H "Authorization: Bearer $IMPULSE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "deployment_id": "clf-churn-v2",
      "inputs": {
        "tenure": 12,
        "MonthlyCharges": 65.5,
        "TotalCharges": 786.0,
        "Contract": "Month-to-month",
        "PaymentMethod": "Electronic check",
        "InternetService": "Fiber optic"
      }
    }'
  ```

  ```python Python theme={null}
  import os
  import requests

  resp = requests.post(
      "https://inference.impulselabs.ai/infer",
      headers={
          "Authorization": f"Bearer {os.environ['IMPULSE_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={
          "deployment_id": "clf-titanic-survived",
          "inputs": {
              "Pclass": 3,
              "Sex": "male",
              "Age": 22,
              "SibSp": 1,
              "Parch": 0,
              "Fare": 7.25,
              "Embarked": "S",
          },
      },
  )
  resp.raise_for_status()
  result = resp.json()
  print(f"Prediction: {result['prediction']}, probability: {result['probability']:.0%}")
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://inference.impulselabs.ai/infer", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.IMPULSE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      deployment_id: "clf-titanic-survived",
      inputs: {
        Pclass: 3,
        Sex: "male",
        Age: 22,
        SibSp: 1,
        Parch: 0,
        Fare: 7.25,
        Embarked: "S",
      },
    }),
  });

  if (!response.ok) {
    const err = await response.json();
    throw new Error(err.detail ?? "Inference failed");
  }

  const { prediction, probability, target } = await response.json();
  console.log(`${target}: ${prediction} (${(probability * 100).toFixed(1)}%)`);
  ```

  ```typescript TypeScript theme={null}
  interface InferRequest {
    deployment_id: string;
    inputs: Record<string, unknown>;
  }

  interface InferResponse {
    prediction: unknown;
    probability: number | null;
    target: string | null;
  }

  async function infer(deploymentId: string, inputs: Record<string, unknown>): Promise<InferResponse> {
    const resp = await fetch("https://inference.impulselabs.ai/infer", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.IMPULSE_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ deployment_id: deploymentId, inputs } satisfies InferRequest),
    });

    if (!resp.ok) {
      const err = await resp.json();
      throw Object.assign(new Error(err.detail ?? "Inference failed"), { status: resp.status });
    }

    return resp.json() as Promise<InferResponse>;
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK — Classification theme={null}
  {
    "prediction": 0,
    "probability": 0.142,
    "target": "Survived"
  }
  ```

  ```json 200 OK — Regression theme={null}
  {
    "prediction": 42350.75,
    "probability": null,
    "target": "SalePrice"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "valid": false,
    "error": "Invalid API key"
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "detail": "No deployment 'clf-titanic-survived' found for user"
  }
  ```

  ```json 429 Too Many Requests theme={null}
  {
    "valid": false,
    "error": "Rate limit exceeded",
    "limit": 120,
    "retry_after_seconds": 34
  }
  ```

  ```json 503 Service Unavailable — model not ready theme={null}
  {
    "detail": "Deployment 'clf-titanic-survived' is not active (status: BUILDING)"
  }
  ```

  ```json 503 Service Unavailable — container unreachable theme={null}
  {
    "detail": "Deployment 'clf-titanic-survived' is not reachable. Retry shortly"
  }
  ```
</ResponseExample>