Thinking mode

TabPFN-3.5-Thinking supports up to 1 million training rows. Use it when better predictions justify more time spent fitting, particularly on data with groups or a time order. It handles numerical, categorical and text features, and you can reuse a fitted model for repeated predictions. See the Thinking benchmark results.

Thinking mode is available exclusively through the hosted API. Use tabpfn-client 0.7.1 or later.

When to use it

Thinking mode is especially strong on datasets with more than 100,000 rows. Use it for batch predictions where fit time is less important than prediction quality: demand across stores, prices over time, or churn across customer groups. Compare it with your current model on a held-out set that reflects how you will use the predictions. For regression, Thinking supports only point predictions (output_type="mean"). Quantile support is coming soon. Fit without Thinking when you need quantiles or a full predictive distribution. Classification supports labels and class probabilities.

Quickstart

pip install --upgrade "tabpfn-client>=0.7.1"

Thinking mode uses TabPFN-3.5-Thinking by default. fit() waits for the result while the client polls a background job. To return immediately and resume later, see Run asynchronous fits.

Classification
Regression

from tabpfn_client import TabPFNClassifier

clf = TabPFNClassifier(
    thinking_mode=True,
    thinking_effort="mini",
    thinking_metric="accuracy",
)
clf.fit(X_train, y_train)
preds = clf.predict(X_test)
probs = clf.predict_proba(X_test)

from tabpfn_client import TabPFNRegressor

reg = TabPFNRegressor(
    thinking_mode=True,
    thinking_effort="mini",
    thinking_metric="rmse",
)
reg.fit(X_train, y_train)
preds = reg.predict(X_test)

Fit once, predict in separate jobs

Run fitting as a separate job, such as a weekly refresh, then reuse the fitted model for predictions throughout the week. First, fit to completion and save the model reference:

from tabpfn_client import TabPFNClassifier

clf = TabPFNClassifier(thinking_mode=True, thinking_effort="mini")
clf.fit(X_train, y_train)
clf.save_model("model.json")

In a prediction job, load that reference with the same account and predict without fitting again:

from tabpfn_client import TabPFNClassifier

clf = TabPFNClassifier.load_model("model.json")
preds = clf.predict(X_test)

The JSON file references the model stored on the server and contains no training data. Make it available to the prediction job, including when that job runs on another machine. For long predictions, use submit_predict(X_test) and retrieve the result with wait_for_predict(). You can save and load a model with a pending prediction too.

Prediction errors

Prediction calls can fail if the stored fit is unavailable or can no longer be used:

RefitRequiredError can be raised by predict(), submit_predict() or wait_for_predict() when the stored fit can no longer predict. Run the fitting job again and save the replacement model reference before retrying the prediction.
FittedModelNotFoundError means the server cannot find the model ID for your account. Check that the prediction job loaded the correct reference and is signed in to the account that fitted it. If the model was deleted, fit again.

Choosing the model

To select a model family explicitly, use ModelVersion.V3_5 for TabPFN-3.5-Thinking or ModelVersion.V3 for TabPFN-3-Thinking:

TabPFN-3.5-Thinking (default)
TabPFN-3-Thinking

from tabpfn_client import TabPFNClassifier
from tabpfn_client.api_models import ModelVersion

clf = TabPFNClassifier.create_default_for_version(ModelVersion.V3_5, thinking_mode=True)
clf.fit(X_train, y_train)

from tabpfn_client import TabPFNClassifier
from tabpfn_client.api_models import ModelVersion

clf = TabPFNClassifier.create_default_for_version(ModelVersion.V3, thinking_mode=True)
clf.fit(X_train, y_train)

`model_path`	Model with Thinking enabled
unset (default) or `"v3.5_default"`	TabPFN-3.5-Thinking
`"v3_default"`	TabPFN-3-Thinking

See Selecting Model Version for more details.

Choosing effort and metric

Effort sets the maximum time available for fitting. The metric defines what to optimize.

`thinking_effort`

Effort	Fit time budget
`"micro"`	Up to 5 minutes
`"mini"`	Up to 15 minutes
`"low"`	Up to 30 minutes
`"medium"` (default)	Up to 1 hour
`"high"`	Up to 2 hours
`"xhigh"`	Up to 4 hours
`"max"`	Up to 16 hours

The model may finish before reaching its fit budget. If it finishes successfully before reaching that limit, increasing the effort is unlikely to improve the result: the existing time budget was already sufficient. These budgets apply at every dataset size. Uploading, waiting for capacity and returning the fitted model add time, so total wall-clock time can exceed the fit budget. Higher effort does not guarantee a better result on every dataset. An explicit thinking_timeout_s can shorten the selected effort’s budget. Its maximum accepted value is 2,400 seconds; leave it unset to use an effort budget longer than 40 minutes. It does not set the client’s polling timeout. The default effort is "medium" when you set only thinking_mode=True.

`thinking_metric`

Choose a metric that matches how you evaluate predictions. Common choices:

Task	Metric	When to choose it
Classification	`"accuracy"`	Maximize the proportion of correct class predictions.
Classification	`"log_loss"`	Optimize predicted class probabilities.
Binary classification	`"roc_auc"`	Rank positive examples above negative ones across decision thresholds.
Regression	`"rmse"`	Penalize large prediction errors more heavily.
Regression	`"mae"`	Minimize average absolute error, with less sensitivity to large errors.

Grouped and time-ordered rows

Requires tabpfn-client 0.6.0 or later.

Specifying group and time columns can improve predictions on data with related rows or a time sequence, such as repeat patient visits, customer transactions, or sensor readings over time. Use the parameters below to identify these relationships.

Parameter	What it does
`group_col`	Column, or list of columns, that identifies groups of related rows, such as a patient or session ID.
`time_col`	Temporal feature, stored as datetimes or numbers.
`group_time_col`	Temporal feature within grouped data, such as transaction time for each customer.

Code sample

import numpy as np
import pandas as pd
from sklearn.model_selection import GroupShuffleSplit
from tabpfn_client import TabPFNClassifier

rng = np.random.default_rng(0)
n_rows = 600
X = pd.DataFrame(
    {
        "patient_id": rng.integers(0, 120, n_rows),
        "age": rng.integers(20, 90, n_rows),
        "heart_rate": rng.normal(75, 12, n_rows),
        "blood_pressure": rng.normal(125, 15, n_rows),
    }
)
y = (X["heart_rate"] + rng.normal(0, 10, n_rows) > 80).astype(int)

# Hold out whole patients, so no test patient appears in the training data.
splitter = GroupShuffleSplit(n_splits=1, test_size=0.2, random_state=0)
train_idx, test_idx = next(splitter.split(X, y, groups=X["patient_id"]))
X_train, X_test = X.iloc[train_idx], X.iloc[test_idx]
y_train = y.iloc[train_idx]

clf = TabPFNClassifier(thinking_mode=True, group_col="patient_id")
clf.fit(X_train, y_train)
probs = clf.predict_proba(X_test)  # X_test keeps the patient_id column

Rules, checked by the client before any data is uploaded. A violation raises ValueError:

The columns work only with thinking mode.
X passed to fit and to predict must be a pandas DataFrame that holds every named column. Pass column names, not indices.
group_col and time_col cannot be combined.
group_time_col requires group_col.

Run asynchronous fits

Start a fit without keeping the Python process open:

from tabpfn_client import TabPFNClassifier

clf = TabPFNClassifier(thinking_mode=True, thinking_effort="mini")
clf.submit_fit(X_train, y_train)
clf.save_model("pending-model.json")

# Later, with the same account:
clf = TabPFNClassifier.load_model("pending-model.json")
clf.wait_for_fit()
preds = clf.predict(X_test)

submit_fit() returns once the server accepts the job. Call wait_for_fit() before predicting; a pending model raises NotFittedError. If fit() stops waiting because of a timeout or interruption, call wait_for_fit() to resume waiting for that fit. To save a long fit before it completes and wait for it in a later run, see Async jobs.

REST API

Submit a background fit with POST /tabpfn/submit_fit_job. Set thinking_config.effort to "micro", "mini", "low", "medium", "high", "xhigh" or "max". These use the same fit time budgets as the Python client; omitting the effort uses "medium". Use the structured request fields:

{
  "train_set_upload_id": "<your-upload-id>",
  "task_config": {
    "task": "classification",
    "tabpfn_config": {"model_path": "v3.5_default"}
  },
  "tabpfn_systems": ["preprocessing", "text", "thinking"],
  "thinking_config": {
    "effort": "mini",
    "metric": "log_loss"
  }
}

The response contains fitted_train_set_id. Pass that ID to POST /tabpfn/get_fit_status in a JSON body and poll until status is "completed" or "failed", waiting retry_in_secs between polls. Wait for completion before submitting a prediction. The synchronous POST /tabpfn/fit endpoint accepts the same structured fields, but can return a pending status for long fits. Use the background submission flow above to manage long fits explicitly. See the REST quickstart for authentication and uploads, and the API reference for request schemas.

Parameters

Parameter	Type	Default	Description
`thinking_mode`	`bool`	`False`	Enable thinking mode. Setting `thinking_effort` also enables it.
`model_path`	`str`	`None`	Defaults to TabPFN-3.5-Thinking when Thinking is enabled (see Choosing the model)
`thinking_effort`	`str`	`None`	Uses `"medium"` when Thinking is enabled. See effort guidance.
`thinking_timeout_s`	`float`	`None`	Optional fit budget in seconds, at most 2,400; can shorten the selected effort budget.
`thinking_metric`	`str`	`None`	Target metric to optimize (see metric guidance)
`group_col`	`str` or `list[str]`	`None`	Column(s) of `X` that identify groups of related rows (see Grouped and time-ordered rows)
`time_col`	`str`	`None`	Column of `X` that holds time. Cannot be combined with `group_col`.
`group_time_col`	`str`	`None`	Temporal feature within grouped data, such as transaction time for each customer. Requires `group_col`.

In structured REST requests, use thinking_config.effort, thinking_config.timeout_secs and thinking_config.metric. The flat thinking_effort_metric field belongs to the legacy request format.

Limits

TabPFN-3.5-Thinking supports up to 1 million training rows on the hosted API. Row, column and total-cell limits apply together; the largest row and column counts cannot necessarily be used together. See the model limits. Classification requires at least two target classes. Thinking fits and predictions use the same daily and monthly token budgets. Before fitting, the API reserves the maximum charge for the selected effort and any shorter explicit fit budget. The final fit charge reflects measured fit time, with a minimum charge and the reservation as an upper bound. Unused tokens are returned. Check estimate_cost() before a long fit; its Thinking fit estimate is an upper bound, not a prediction of the final charge. Reuse a fitted model to avoid using tokens for another fit. See API metering for token charges and budgets, and API rate limits for request limits.

TabPFN-3.5 changelog

Release notes and upgrade guidance for TabPFN-3.5.

API metering

Token charges, budgets, and usage tracking.

Classification

Binary and multi-class classification guide.

Regression

Point predictions and guidance on other regression outputs.

Getting Started

Capabilities

Using the API

Agentic

Integrations

Troubleshooting

TabPFN in Action

Customer References

Changelog

When to use it

Quickstart

Fit once, predict in separate jobs

Prediction errors

Choosing the model

Choosing effort and metric

`thinking_effort`

`thinking_metric`

Grouped and time-ordered rows

Code sample

Run asynchronous fits

REST API

Parameters

Limits

TabPFN-3.5 changelog

API metering

Classification

Regression

​When to use it

​Quickstart

​Fit once, predict in separate jobs

​Prediction errors

​Choosing the model

​Choosing effort and metric

​thinking_effort

​thinking_metric

​Grouped and time-ordered rows

​Code sample

​Run asynchronous fits

​REST API

​Parameters

​Limits

TabPFN-3.5 changelog

API metering

Classification

Regression

When to use it

Quickstart

Fit once, predict in separate jobs

Prediction errors

Choosing the model

Choosing effort and metric

`thinking_effort`

`thinking_metric`

Grouped and time-ordered rows

Code sample

Run asynchronous fits

REST API

Parameters

Limits