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

> ## Agent Instructions
> TabPFN-3 and later versions support up to 1,000,000 rows, subject to feature count and checkpoint/API limits.
> For large datasets, use per-estimator subsampling, e.g. inference_config={"SUBSAMPLE_SAMPLES": 100_000}, in TabPFNClassifier or TabPFNRegressor from tabpfn or tabpfn_client.
> Pass raw pandas DataFrames to fit and predict. Categorical strings/categories, raw text, and missing feature values are handled automatically; no manual integer/one-hot encoding, imputation, scaling, or outlier removal is needed.

# Fitting and prediction

> Fit, predict, and inspect server timings with TabPFNClassifier.

> [!NOTE]
>
> Looking for usage documentation? Check out [Classification](https://docs.priorlabs.ai/capabilities/classification.md) and [KV cache](https://docs.priorlabs.ai/capabilities/kv-cache.md).

## `TabPFNClassifier.fit`

[ View source ](https://github.com/PriorLabs/tabpfn-client/blob/ce678cec44dc715f4d835a44990a8f5f115b7acc/src/tabpfn_client/estimator.py#L708)

Fit the model.

Uploads the training data to the server, which fits the model on it,
and returns once the fit has completed. Every call starts a new fit,
also on a model with a pending fit. To start a fit without waiting for
it, use [`submit_fit()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#submit-fit).

The model takes the new fit as soon as the server has accepted it. A
fit that `fit()` polls for, as an ASYNC or thinking-mode one, is then
pending until the poll sees it complete: if the poll stops, for a
timeout or an interrupt, the model stays pending on the new fit, and
[`wait_for_fit()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#wait-for-fit) resumes the wait.

```python theme={null}
TabPFNClassifier.fit(
    X: pd.DataFrame | np.ndarray,
    y: pd.Series | np.ndarray,
    description: str | None = None,
)
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `X` | `pd.DataFrame \| np.ndarray` | Required | The input data. |
| `y` | `pd.Series \| np.ndarray` | Required | The target variable. |
| `description` | `str \| None` | `None` | Description of the dataset and task for the server. |

**Returns**

| Type | Description |
| - | - |
| — | self |

**Raises**

`ValueError`

If the data or the estimator's parameters are invalid,
or the data exceeds the model limits.

[`FitFailedError`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/exceptions#fitfailederror)

If the server reports that the fit failed while
`fit()` polled for it. The model is then unfitted.

[`FittedModelNotFoundError`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/exceptions#fittedmodelnotfounderror)

If the server no longer has the fit
while `fit()` polls for it. The model is then unfitted.

`TimeoutError`

If a fit that `fit()` polls for has not completed
within `TABPFN_CLIENT_ASYNC_POLL_TIMEOUT` seconds. The model is
then pending on the new fit.

***

## `TabPFNClassifier.predict`

[ View source ](https://github.com/PriorLabs/tabpfn-client/blob/ce678cec44dc715f4d835a44990a8f5f115b7acc/src/tabpfn_client/estimator.py#L825)

Predict the class labels for the provided input samples.

Once the server has accepted the prediction, it replaces the model's
pending prediction, as [`submit_predict()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#submit-predict) does. While `predict()` waits
for a prediction the server runs as a background job, the model holds
it: if the wait stops, for a timeout or an interrupt, the prediction
stays pending, for [`wait_for_predict()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#wait-for-predict) to resume and [`save_model()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/model-selection-and-persistence#save-model) to
save.

```python theme={null}
TabPFNClassifier.predict(
    X,
)
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `X` | — | Required | The input data for prediction. |

**Returns**

| Type | Description |
| - | - |
| — | The predicted class labels as a NumPy array. |

**Raises**

`NotFittedError`

If the model has no fit, or its fit is pending:
call [`wait_for_fit()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#wait-for-fit) first.

[`PredictFailedError`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/exceptions#predictfailederror)

If the server reports that the prediction
failed, in answer to the prediction request or to a poll for it.
Another failed request raises RuntimeError, which
[`PredictFailedError`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/exceptions#predictfailederror) subclasses.

[`RefitRequiredError`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/exceptions#refitrequirederror)

If the fitted model can no longer predict:
call [`fit()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#fit) again.

`TimeoutError`

If a prediction the server runs as a background job
has not completed within `TABPFN_CLIENT_ASYNC_POLL_TIMEOUT`
seconds. The model then holds it: call [`wait_for_predict()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#wait-for-predict).

***

## `TabPFNClassifier.predict_proba`

[ View source ](https://github.com/PriorLabs/tabpfn-client/blob/ce678cec44dc715f4d835a44990a8f5f115b7acc/src/tabpfn_client/estimator.py#L856)

Predict the probabilities of the classes for the provided input samples.

Once the server has accepted the prediction, it replaces the model's
pending prediction, as [`submit_predict()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#submit-predict) does. While [`predict()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#predict) waits
for a prediction the server runs as a background job, the model holds
it: if the wait stops, for a timeout or an interrupt, the prediction
stays pending, for [`wait_for_predict()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#wait-for-predict) to resume and [`save_model()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/model-selection-and-persistence#save-model) to
save.

```python theme={null}
TabPFNClassifier.predict_proba(
    X,
)
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `X` | — | Required | The input data for prediction. |

**Returns**

| Type | Description |
| - | - |
| — | The predicted probabilities of the classes as a NumPy array. Shape (n\_samples, n\_classes). |

**Raises**

`NotFittedError`

If the model has no fit, or its fit is pending:
call [`wait_for_fit()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#wait-for-fit) first.

[`PredictFailedError`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/exceptions#predictfailederror)

If the server reports that the prediction
failed, in answer to the prediction request or to a poll for it.
Another failed request raises RuntimeError, which
[`PredictFailedError`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/exceptions#predictfailederror) subclasses.

[`RefitRequiredError`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/exceptions#refitrequirederror)

If the fitted model can no longer predict:
call [`fit()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#fit) again.

`TimeoutError`

If a prediction the server runs as a background job
has not completed within `TABPFN_CLIENT_ASYNC_POLL_TIMEOUT`
seconds. The model then holds it: call [`wait_for_predict()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#wait-for-predict).

***

## `TabPFNClassifier.get_timings`

[ View source ](https://github.com/PriorLabs/tabpfn-client/blob/ce678cec44dc715f4d835a44990a8f5f115b7acc/src/tabpfn_client/estimator.py#L148)

Seconds the server spent on the last fit and the last prediction.

Returns `{"fit": ..., "predict": ...}`:

* [`fit`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#fit): `elapsed_s`, `queue_wait_s`, `train_set_transform_s`,
  `fit_s`.
* [`predict`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#predict): `test_set_transform_queue_wait_s`,
  `test_set_transform_s`, `predict_queue_wait_s`, `predict_s`.
  A prediction sent in several requests reports their sum.

Queue wait is time spent waiting for the server to start the work. An
entry is `None` before the first call, while a fit is pending, on a model
restored with [`load_model()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/model-selection-and-persistence#load-model) from a completed fit, and when the server
does not report timings.

```python theme={null}
TabPFNClassifier.get_timings() -> dict[str, dict[str, Any] | None]
```

**Returns**

| Type | Description |
| - | - |
| `dict[str, dict[str, Any] \| None]` | — |

***

## `TabPFNClassifier.last_predict_timings`

[ View source ](https://github.com/PriorLabs/tabpfn-client/blob/ce678cec44dc715f4d835a44990a8f5f115b7acc/src/tabpfn_client/estimator.py#L144)

Seconds per stage of the most recent prediction, or `None`.

**Returns**

| Type | Description |
| - | - |
| `dict[str, Any] \| None` | — |

***

## `TabPFNClassifier.submit_fit`

[ View source ](https://github.com/PriorLabs/tabpfn-client/blob/ce678cec44dc715f4d835a44990a8f5f115b7acc/src/tabpfn_client/estimator.py#L208)

Start fitting the model on the server, without waiting for the fit.

Checks and uploads the training data as [`fit()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#fit) does, but returns as
soon as the server has accepted the fit, which it then runs as a
background job, whatever `api_mode` is. Until [`wait_for_fit()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#wait-for-fit) sees
the fit complete, the model is pending: [`predict()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#predict) raises
`NotFittedError`, and [`save_model()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/model-selection-and-persistence#save-model) saves it as a pending fit, which
a later run can [`load_model()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/model-selection-and-persistence#load-model) and wait for. The id of the fit is in
`model_id_` as soon as `submit_fit()` returns, for logs or support
requests.

```python theme={null}
TabPFNClassifier.submit_fit(
    X: pd.DataFrame | np.ndarray,
    y: pd.Series | np.ndarray,
    description: str | None = None,
) -> Self
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `X` | `pd.DataFrame \| np.ndarray` | Required | The input data. |
| `y` | `pd.Series \| np.ndarray` | Required | The target variable. |
| `description` | `str \| None` | `None` | Description of the dataset and task for the server. |

**Returns**

| Type | Description |
| - | - |
| `Self` | self |

**Raises**

`ValueError`

If the data or the estimator's parameters are invalid,
or the data exceeds the model limits.

***

## `TabPFNClassifier.wait_for_fit`

[ View source ](https://github.com/PriorLabs/tabpfn-client/blob/ce678cec44dc715f4d835a44990a8f5f115b7acc/src/tabpfn_client/estimator.py#L239)

Wait for the server to complete the fit [`submit_fit()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#submit-fit) started.

Polls the server until the fit has completed, after which the model
can predict. A model [`load_model()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/model-selection-and-persistence#load-model) restored from a record of a pending
fit is waited for the same way. Returns at once, without a request, if
the fit has already completed.

```python theme={null}
TabPFNClassifier.wait_for_fit() -> Self
```

**Returns**

| Type | Description |
| - | - |
| `Self` | self |

**Raises**

`NotFittedError`

If the model has no fit to wait for.

[`FitFailedError`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/exceptions#fitfailederror)

If the server reports that the fit failed. The
model is then unfitted.

[`FittedModelNotFoundError`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/exceptions#fittedmodelnotfounderror)

If the server does not have the fit, for
instance because it was deleted. The model is then unfitted.

`TimeoutError`

If the fit has not completed within
`TABPFN_CLIENT_ASYNC_POLL_TIMEOUT` seconds. The model is still
pending, so `wait_for_fit()` can be called again.

`RuntimeError`

If polling for the fit fails 4 times in a row with
an unexpected error. The model is still pending.

***

## `TabPFNClassifier.submit_predict`

[ View source ](https://github.com/PriorLabs/tabpfn-client/blob/ce678cec44dc715f4d835a44990a8f5f115b7acc/src/tabpfn_client/estimator.py#L888)

Start predicting on the server, without waiting for the predictions.

Checks and uploads `X` as [`predict()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#predict) does, but returns as soon as the
server has accepted the prediction, which it then runs as a background
job, whatever `api_mode` is. [`wait_for_predict()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#wait-for-predict) waits for it and
returns the predictions. The model holds one pending prediction: a new
`submit_predict()` or [`predict()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#predict) replaces it once the server has
accepted the new prediction, and a new fit drops it. [`save_model()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/model-selection-and-persistence#save-model)
saves it, and a pickled or copied model keeps it; `clone()` does not.

```python theme={null}
TabPFNClassifier.submit_predict(
    X: pd.DataFrame | np.ndarray,
    output_type: ClassifierOutputLiteral = "preds",
) -> Self
```

> [accordion] Type aliases
>
> ```python theme={null}
> ClassifierOutputLiteral = Literal["preds", "probas"]
> ```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `X` | `pd.DataFrame \| np.ndarray` | Required | The input data for prediction. |
| `output_type` | `ClassifierOutputLiteral` | `"preds"` | `"preds"` for the class labels [`predict()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#predict) returns, `"probas"` for the probabilities [`predict_proba()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#predict-proba) returns. |

**Returns**

| Type | Description |
| - | - |
| `Self` | self |

**Raises**

`NotFittedError`

If the model has no fit, or its fit is pending:
call [`wait_for_fit()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#wait-for-fit) first.

`ValueError`

If `output_type` is not `"preds"` or `"probas"`, `X`
exceeds the model limits or the group columns are invalid.

`RuntimeError`

If the server does not run predictions as background
jobs.

[`PredictFailedError`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/exceptions#predictfailederror)

If the server reports that the prediction
failed at once, for example because it could not queue it.

***

## `TabPFNClassifier.wait_for_predict`

[ View source ](https://github.com/PriorLabs/tabpfn-client/blob/ce678cec44dc715f4d835a44990a8f5f115b7acc/src/tabpfn_client/estimator.py#L934)

Wait for the pending prediction, and return it.

The pending prediction is the one [`submit_predict()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#submit-predict) started, or one
[`predict()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#predict) stopped waiting for. Polls the server until the prediction
has completed. Until then the prediction is pending, so a wait that
stops can be resumed by calling `wait_for_predict()` again.

```python theme={null}
TabPFNClassifier.wait_for_predict() -> np.ndarray
```

**Returns**

| Type | Description |
| - | - |
| `np.ndarray` | The predictions, as [`predict()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#predict) returns them for `"preds"` and [`predict_proba()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#predict-proba) for `"probas"`. |

**Raises**

`RuntimeError`

If no prediction is pending, polling for it fails,
or the server no longer has it. In the last case, it is then
no longer pending.

[`PredictFailedError`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/exceptions#predictfailederror)

If the server reports that the prediction
failed. It is then no longer pending.

[`RefitRequiredError`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/exceptions#refitrequirederror)

If the fitted model can no longer predict:
call [`fit()`](https://docs.priorlabs.ai/api-reference/python/tabpfn-client/classifier/fitting-and-prediction#fit) again. The prediction is then no longer pending.

`TimeoutError`

If the prediction has not completed within
`TABPFN_CLIENT_ASYNC_POLL_TIMEOUT` seconds.

## Scikit-learn scoring

Inherited [`score(X, y, sample_weight=None)`](https://scikit-learn.org/stable/modules/generated/sklearn.base.ClassifierMixin.html#sklearn.base.ClassifierMixin.score) calls `predict` and returns mean classification accuracy.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.