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

# Inference

> Run predictions on new data using a trained model.

Once a model is ready, run inference to get predictions, clusters, anomaly scores, embeddings, or search results depending on the model type.

<CardGroup cols={1}>
  <Card title="Infer (File Upload)" icon="play" href="/api-reference/inference/infer-file-upload">
    Upload a file and get results in the response. Best for small files.
  </Card>

  <Card title="Async Infer (File Upload)" icon="clock" href="/api-reference/inference/async-infer-file-upload">
    Upload a file and poll for results. Best for larger files.
  </Card>

  <Card title="Async Infer (Dataset)" icon="database" href="/api-reference/inference/async-infer-dataset">
    Run inference on an existing dataset. Returns a job ID for polling.
  </Card>
</CardGroup>

***

## Output Formats

All inference endpoints support three output formats via the `output_type` parameter:

| Format    | Content-Type               | Description                                                                                                                               |
| --------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `json`    | `application/json`         | Column-oriented JSON dict. Each key maps to a list of values.                                                                             |
| `csv`     | `text/csv`                 | Standard CSV file with one row per input instance.                                                                                        |
| `parquet` | `application/octet-stream` | Apache Parquet file. Same columns as CSV. Includes `model_id`, `model_name`, `model_version_id`, and `model_type` in file-level metadata. |

The specific columns returned depend on the model type:

***

### Prediction

For binary classification, multiclass classification, and regression.

| Column            | Type            | Present             | Description                                                                                                                |
| ----------------- | --------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `id`              | integer         | Always              | Row index from the input data.                                                                                             |
| `prediction`      | string or float | Always              | Predicted label (classification) or value (regression).                                                                    |
| `prediction_prob` | float           | Classification only | Confidence in the predicted class. Ranges from 0.5 to 1.0 for binary; 0 to 1.0 for multiclass. Not present for regression. |

**Binary classification:**

<Tabs sync={false}>
  <Tab title="JSON">
    ```json theme={null}
    {
      "id": [0, 1, 2],
      "prediction": ["yes", "no", "yes"],
      "prediction_prob": [0.88, 0.95, 0.7]
    }
    ```
  </Tab>

  <Tab title="CSV">
    ```csv theme={null}
    id,prediction,prediction_prob
    0,yes,0.88
    1,no,0.95
    2,yes,0.7
    ```
  </Tab>
</Tabs>

**Multiclass classification:**

<Tabs sync={false}>
  <Tab title="JSON">
    ```json theme={null}
    {
      "id": [0, 1, 2],
      "prediction": ["cat_A", "cat_B", "cat_C"],
      "prediction_prob": [0.82, 0.91, 0.65]
    }
    ```
  </Tab>

  <Tab title="CSV">
    ```csv theme={null}
    id,prediction,prediction_prob
    0,cat_A,0.82
    1,cat_B,0.91
    2,cat_C,0.65
    ```
  </Tab>
</Tabs>

**Regression:**

<Tabs sync={false}>
  <Tab title="JSON">
    ```json theme={null}
    {
      "id": [0, 1, 2],
      "prediction": [42.5, 17.3, 89.1]
    }
    ```
  </Tab>

  <Tab title="CSV">
    ```csv theme={null}
    id,prediction
    0,42.5
    1,17.3
    2,89.1
    ```
  </Tab>
</Tabs>

***

### Clustering

| Column                | Type    | Description                                |
| --------------------- | ------- | ------------------------------------------ |
| `id`                  | integer | Row index from the input data.             |
| `cluster_label`       | integer | Cluster assignment (0-indexed).            |
| `cluster_description` | string  | Human-readable description of the cluster. |

<Tabs sync={false}>
  <Tab title="JSON">
    ```json theme={null}
    {
      "id": [0, 1, 2, 3],
      "cluster_label": [0, 1, 0, 2],
      "cluster_description": [
        "High-income urban professionals with frequent purchases",
        "Budget-conscious suburban families",
        "High-income urban professionals with frequent purchases",
        "Young students with occasional spending"
      ]
    }
    ```
  </Tab>

  <Tab title="CSV">
    ```csv theme={null}
    id,cluster_label,cluster_description
    0,0,High-income urban professionals with frequent purchases
    1,1,Budget-conscious suburban families
    2,0,High-income urban professionals with frequent purchases
    3,2,Young students with occasional spending
    ```
  </Tab>
</Tabs>

***

### Anomaly Detection

Output depends on the `anomaly_format` parameter.

#### `anomaly_format=ids_only` (default)

| Column          | Type             | Description                       |
| --------------- | ---------------- | --------------------------------- |
| `anomalous_ids` | list of integers | Row indices flagged as anomalous. |

<Tabs sync={false}>
  <Tab title="JSON">
    ```json theme={null}
    {
      "anomalous_ids": [3, 17, 42]
    }
    ```
  </Tab>

  <Tab title="CSV">
    ```csv theme={null}
    anomalous_ids
    3
    17
    42
    ```
  </Tab>
</Tabs>

#### `anomaly_format=per_row`

| Column          | Type    | Description                                                   |
| --------------- | ------- | ------------------------------------------------------------- |
| `id`            | integer | Row index from the input data.                                |
| `is_anomaly`    | boolean | Whether this row is flagged as anomalous.                     |
| `anomaly_score` | float   | Anomaly score (higher values indicate greater anomalousness). |

<Tabs sync={false}>
  <Tab title="JSON">
    ```json theme={null}
    {
      "id": [0, 1, 2, 3],
      "is_anomaly": [false, false, false, true],
      "anomaly_score": [0.021, 0.045, 0.033, 0.892]
    }
    ```
  </Tab>

  <Tab title="CSV">
    ```csv theme={null}
    id,is_anomaly,anomaly_score
    0,false,0.021
    1,false,0.045
    2,false,0.033
    3,true,0.892
    ```
  </Tab>
</Tabs>

***

### Embeddings

| Column              | Type    | Description                                                                 |
| ------------------- | ------- | --------------------------------------------------------------------------- |
| `id`                | integer | Row index from the input data.                                              |
| `dim_0` ... `dim_N` | float   | Embedding vector dimensions. The number of dimensions depends on the model. |

<Tabs sync={false}>
  <Tab title="JSON">
    ```json theme={null}
    {
      "id": [0, 1, 2],
      "dim_0": [0.123, 0.456, -0.789],
      "dim_1": [-0.321, 0.654, 0.012],
      "dim_2": [0.111, -0.222, 0.333]
    }
    ```
  </Tab>

  <Tab title="CSV">
    ```csv theme={null}
    id,dim_0,dim_1,dim_2
    0,0.123,-0.321,0.111
    1,0.456,0.654,-0.222
    2,-0.789,0.012,0.333
    ```
  </Tab>
</Tabs>

***

### Search

| Column                 | Type   | Description                                             |
| ---------------------- | ------ | ------------------------------------------------------- |
| Input row ID (key)     | string | Row index from the inference data.                      |
| Matched row ID (value) | string | Row index of the closest match in the training dataset. |

<Tabs sync={false}>
  <Tab title="JSON">
    ```json theme={null}
    {
      "search_results": {
        "0": "42",
        "1": "17",
        "2": "103"
      }
    }
    ```
  </Tab>

  <Tab title="CSV">
    ```csv theme={null}
    query_id,match_id
    0,42
    1,17
    2,103
    ```
  </Tab>
</Tabs>

***

### Factor Analysis

Output has one row per discovered factor, not per input instance.

| Column               | Type    | Description                                                  |
| -------------------- | ------- | ------------------------------------------------------------ |
| `factor_id`          | integer | Factor index (0-indexed).                                    |
| `factor_description` | string  | Human-readable description of what this factor represents.   |
| `captured_variance`  | float   | Proportion of variance in the data explained by this factor. |

<Tabs sync={false}>
  <Tab title="JSON">
    ```json theme={null}
    {
      "factor_id": [0, 1, 2],
      "factor_description": [
        "Income and spending power",
        "Geographic and urban/rural divide",
        "Age and career stage"
      ],
      "captured_variance": [0.35, 0.22, 0.15]
    }
    ```
  </Tab>

  <Tab title="CSV">
    ```csv theme={null}
    factor_id,factor_description,captured_variance
    0,Income and spending power,0.35
    1,Geographic and urban/rural divide,0.22
    2,Age and career stage,0.15
    ```
  </Tab>
</Tabs>