> ## 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.

# Run Predictions

> **Deprecated:** Prefer `tabpfn-client` or `POST /tabpfn/predict`. See the [TabPFN-3 changelog](/changelog/tabpfn-3).

Run inference using a previously fitted TabPFN model. Upload your test dataset and specify the model ID from your previous `/v1/fit` call. The endpoint returns predicted probabilities or values depending on the task type.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/predict
openapi: 3.1.0
info:
  title: TabPFN API
  description: >-
    Prior Labs TabPFN API. **Prefer
    [tabpfn-client](https://github.com/PriorLabs/tabpfn-client)**. Current
    integration surface: **`/tabpfn/*` JSON routes** (prepare uploads, fit,
    predict, limits). **`/v1/*` multipart routes are deprecated.** See the
    [Changelog](/changelog).
  version: 2.0.0
  contact:
    name: Prior Labs
    email: hello@priorlabs.ai
servers:
  - url: https://api.priorlabs.ai
    description: Production TabPFN API (`/tabpfn/*` current; `/v1/*` deprecated)
security:
  - BearerAuth: []
paths:
  /v1/predict:
    post:
      tags:
        - Prediction
      summary: Run Predictions
      description: >-
        **Deprecated:** Prefer `tabpfn-client` or `POST /tabpfn/predict`. See
        the [TabPFN-3 changelog](/changelog/tabpfn-3).


        Run inference using a previously fitted TabPFN model. Upload your test
        dataset and specify the model ID from your previous `/v1/fit` call. The
        endpoint returns predicted probabilities or values depending on the task
        type.
      operationId: predict_v1_deprecated
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - data
                - file
              properties:
                data:
                  type: string
                  description: >-
                    A JSON string defining the prediction request parameters.


                    **Required fields:**

                    - `model_id` (`str`) - Model ID from your previous `/v1/fit`
                    call

                    - `task` (`str`) - Task type: `"classification"` or
                    `"regression"`


                    **Optional Config Parameters:**

                    - `systems` (`list[str]`) - default: `["preprocessing",
                    "text"]`. 

                    **The following preprocessing systems are supported**: 
                         - `["preprocessing"]` - Applies skrub preprocessing, 
                       - `["text"]` - Adds text embeddings for text columns. 
                    - `n_estimators` (`int`) - Number of estimators in the
                    ensemble (1-10)

                    - `model_path` (`str`) - Model checkpoint path from
                    [HuggingFace](https://huggingface.co/Prior-Labs/tabpfn_3/tree/main)

                    - `categorical_features_indices` (`List[int]`) - Indices of
                    categorical features

                    - `softmax_temperature` (`float`) - Temperature for softmax
                    scaling

                    - `average_before_softmax` (`bool`) - Average before
                    applying softmax

                    - `ignore_pretraining_limits` (`bool`) - Ignore pretraining
                    limits

                    - `inference_precision` (`str`) - Inference precision
                    ("float32", "float16", "auto")

                    - `random_state` (`int`) - Random seed for reproducibility

                    - `balance_probabilities` (`bool`) - Balance class
                    probabilities


                    **Optional Params (output configuration):**

                    - `output_type` (`str`) - Determines prediction output
                    format
                      - Classification: `"probas"` (default, probabilities) or `"preds"` (predictions)
                      - Regression: `"mean"` (default, mean value) or `"full"` (includes quantiles, ei, pi)
                file:
                  type: string
                  format: binary
                  description: CSV file containing the dataset to predict on.
            examples:
              classification:
                summary: Classification task
                value:
                  data: >-
                    {"model_id": "123e4567-e89b-12d3-a456-426614174000", "task":
                    "classification", "params": {"output_type":
                    "probabilities"}}
                  file: '[binary data]'
              regression:
                summary: Regression task
                value:
                  data: >-
                    {"model_id": "123e4567-e89b-12d3-a456-426614174000", "task":
                    "regression", "config": {"n_estimators": 8}}
                  file: '[binary data]'
      responses:
        '200':
          description: >-
            Prediction completed successfully — returns predicted values or
            probabilities depending on the task.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PredictionResponse'
              examples:
                Classification with probabilities:
                  summary: Classification with probabilities
                  value:
                    duration_seconds: 15
                    prediction:
                      - - 0.1
                        - 0.9
                      - - 0.8
                        - 0.2
                    task: classification
                    params:
                      average_before_softmax: false
                      categorical_features_indices: null
                      device:
                        - cpu
                      differentiable_input: false
                      fit_mode: fit_preprocessors
                      ignore_pretraining_limits: true
                      inference_config: null
                      inference_precision: auto
                      memory_saving_mode: true
                      model_path: auto
                      n_estimators: 8
                      n_jobs: null
                      n_preprocessing_jobs: 4
                      random_state: 42
                      softmax_temperature: 0.2
                    used_credits: 10
                    remaining_quota: 90
                Classification with class predictions:
                  summary: Classification with class predictions
                  value:
                    duration_seconds: 12
                    prediction:
                      - class_1
                      - class_0
                      - class_1
                    task: classification
                    params:
                      average_before_softmax: false
                      categorical_features_indices: null
                      device:
                        - cpu
                      differentiable_input: false
                      fit_mode: fit_preprocessors
                      ignore_pretraining_limits: true
                      inference_config: null
                      inference_precision: auto
                      memory_saving_mode: true
                      model_path: auto
                      n_estimators: 8
                      n_jobs: null
                      n_preprocessing_jobs: 4
                      random_state: 42
                      softmax_temperature: 0.2
                    used_credits: 8
                    remaining_quota: 92
                Regression prediction:
                  summary: Regression prediction
                  value:
                    duration_seconds: 10
                    prediction:
                      - 1250.5
                      - 3200.8
                      - 980.2
                      - 2100
                    task: regression
                    params:
                      average_before_softmax: false
                      categorical_features_indices: null
                      device:
                        - cpu
                      differentiable_input: false
                      fit_mode: fit_preprocessors
                      ignore_pretraining_limits: true
                      inference_config: null
                      inference_precision: auto
                      memory_saving_mode: true
                      model_path: auto
                      n_estimators: 8
                      n_jobs: null
                      n_preprocessing_jobs: 4
                      random_state: 42
                      softmax_temperature: 0.2
                    used_credits: 5
                    remaining_quota: 95
        '400':
          description: Invalid request — dataset file missing or malformed input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: error.bad_request
                detail: You must upload a dataset `file` for prediction.
                retryable: false
                support: https://discord.com/invite/VJRuU3bSxt
        '401':
          description: |-
            Unauthorized — authentication required or credentials invalid.

            **Possible causes:**
            - Missing or malformed `Authorization` header
            - Invalid or expired JWT token
            - User not found (token references a deleted account)
            - JWT decode errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_token:
                  value:
                    code: auth.unauthorized
                    detail: Not authenticated
                    retryable: false
                    support: https://discord.com/invite/VJRuU3bSxt
                invalid_credentials:
                  value:
                    code: auth.unauthorized
                    detail: Could not validate credentials
                    retryable: false
                    support: https://discord.com/invite/VJRuU3bSxt
        '403':
          description: Forbidden — user account not verified or insufficient permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: auth.forbidden
                detail: User account not verified
                retryable: false
                support: https://discord.com/invite/VJRuU3bSxt
        '404':
          description: >-
            Model not found — the provided model ID does not exist or has
            expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: error.not_found
                detail: >-
                  Fitted model with ID 123e4567-e89b-12d3-a456-426614174000 not
                  found
                retryable: false
                support: https://discord.com/invite/VJRuU3bSxt
        '422':
          description: Validation error — incorrect or missing fields in the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      deprecated: true
      security:
        - BearerAuth: []
      x-codeSamples:
        - lang: python
          label: Getting Started Example
          source: |-
            import os, json, requests

            # Define your test dataset path
            test_path = "test.csv"

            # Get your API key from the environment
            api_key = os.getenv("PRIORLABS_API_KEY")
            headers = {"Authorization": f"Bearer {api_key}"}

            # Create prediction payload
            payload = {
             "task": "classification",
             "model_id": model_id, # Use model_id from your /v1/fit call
            }

            files = {
                "data": (None, json.dumps(payload), "application/json"),
                "file": (test_path, open(test_path, "rb")),
            }

            predict_response = requests.post(
                "https://api.priorlabs.ai/v1/predict",
                headers=headers,
                files=files,
            )

            print("✅ Predictions:")
            print(json.dumps(predict_response.json(), indent=2))
        - lang: python
          label: Example with All Parameters
          source: |-
            import os, json, requests

            # Define your test dataset path
            test_path = "test.csv"

            # Get your API key from the environment
            api_key = os.getenv("PRIORLABS_API_KEY")
            headers = {"Authorization": f"Bearer {api_key}"}

            # Create prediction payload
            payload = {
             "task": "classification",
             "model_id": model_id, # Use model_id from your /v1/fit call

             # Optional model parameters and configuration
             "params": {
                 "output_type": "probas" # Use "preds" for hard labels
             },
             "systems": ["preprocessing", "text"],
             "config": {
                "n_estimators": 4,
                "categorical_features_indices": [0, 2, 5],
                "softmax_temperature": 0.75,
                "average_before_softmax": False,
                "inference_precision": "float32",
                "random_state": 42,
                "inference_config": {"batch_size": 1024},
                "model_path": "tabpfn-v3-classifier-v3_default.ckpt",
                "balance_probabilities": True,
                "ignore_pretraining_limits": False
             }
            }

            files = {
                "data": (None, json.dumps(payload), "application/json"),
                "file": (test_path, open(test_path, "rb")),
            }

            predict_response = requests.post(
                "https://api.priorlabs.ai/v1/predict",
                headers=headers,
                files=files,
            )

            print("✅ Predictions:")
            print(json.dumps(predict_response.json(), indent=2))
components:
  schemas:
    PredictionResponse:
      type: object
      required:
        - duration_seconds
        - prediction
        - task
        - used_credits
        - remaining_quota
      properties:
        duration_seconds:
          type: integer
          description: Time taken (in seconds) to complete the prediction.
        prediction:
          description: >-
            The prediction output. Format depends on task and output_type:

            - **Regression**: List of floats (e.g., `[1250.5, 3200.8, 980.2]`)

            - **Classification with `output_type: probas`**: List of lists
            (probabilities) (e.g., `[[0.1, 0.9], [0.8, 0.2]]`)

            - **Classification with `output_type: preds`**: List of classes
            (e.g., `["class_0", "class_1"]`)
          oneOf:
            - type: array
              items:
                type: number
              description: Regression predictions or classification probabilities
            - type: array
              items:
                type: array
                items:
                  type: number
              description: Classification probabilities (list of lists)
            - type: array
              items:
                type: string
              description: Classification predictions (list of class names)
        task:
          $ref: '#/components/schemas/PredictionTask'
        params:
          type: object
          description: The inference parameters that were used during prediction.
          properties:
            average_before_softmax:
              type: boolean
              description: Whether to average before applying softmax.
            categorical_features_indices:
              type: array
              items:
                type: integer
              nullable: true
              description: Indices of categorical features.
            ignore_pretraining_limits:
              type: boolean
              description: Whether to ignore pretraining limits.
            inference_config:
              type: object
              nullable: true
              description: Additional inference configuration parameters.
            inference_precision:
              type: string
              description: Inference precision (e.g., "auto", "float32", "float16").
            model_path:
              type: string
              description: Model checkpoint path used for inference.
            n_estimators:
              type: integer
              description: Number of ensemble estimators used.
            n_preprocessing_jobs:
              type: integer
              description: Number of preprocessing jobs.
            random_state:
              type: integer
              nullable: true
              description: Random seed used for reproducibility.
            softmax_temperature:
              type: number
              description: Softmax temperature parameter used.
        used_credits:
          type: integer
          description: The number of credits consumed by this API call.
        remaining_quota:
          type: integer
          description: Your remaining credit balance after this request.
      example:
        duration_seconds: 15
        prediction:
          - 0.1
          - 0.9
          - 0.3
          - 0.7
        task: classification
        params:
          average_before_softmax: false
          categorical_features_indices: null
          ignore_pretraining_limits: true
          inference_config: null
          inference_precision: auto
          model_path: auto
          n_estimators: 8
          n_preprocessing_jobs: 4
          random_state: 42
          softmax_temperature: 0.2
        used_credits: 10
        remaining_quota: 90
    ErrorResponse:
      type: object
      required:
        - code
        - detail
        - retryable
        - support
      properties:
        code:
          type: string
          description: Error category code (e.g., auth.unauthorized, rate.limit.exceeded)
          example: auth.unauthorized
        detail:
          type: string
          description: Human-readable error message describing what went wrong.
          example: Invalid authentication credentials
        retryable:
          type: boolean
          description: Indicates whether the request can be retried.
          example: false
        support:
          type: string
          description: URL to get support for this error.
          example: https://discord.com/invite/VJRuU3bSxt
      example:
        code: auth.unauthorized
        detail: Invalid authentication credentials
        retryable: false
        support: https://discord.com/invite/VJRuU3bSxt
    ValidationError:
      type: object
      required:
        - code
        - detail
        - errors
        - retryable
        - support
      properties:
        code:
          type: string
          description: Error category code for validation errors
          example: validation.failed
        detail:
          type: string
          description: Human-readable validation error message
          example: Validation error for FitRequest
        errors:
          type: array
          description: Array of field-level validation errors
          items:
            type: object
            properties:
              field:
                type: string
                description: Field name where the error occurred
                example: task
              message:
                type: string
                description: Error message for this field
                example: field required
        retryable:
          type: boolean
          description: Indicates whether the request can be retried
          example: false
        support:
          type: string
          description: URL to get support for this error
          example: https://discord.com/invite/VJRuU3bSxt
      example:
        code: validation.failed
        detail: Validation error for FitRequest
        errors:
          - field: task
            message: field required
          - field: systems
            message: >-
              Invalid system: invalid_system. Must be one of: ['preprocessing',
              'text']
        retryable: false
        support: https://discord.com/invite/VJRuU3bSxt
    PredictionTask:
      type: string
      enum:
        - classification
        - regression
      description: >-
        Specifies the type of task to perform — either classification or
        regression.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer token for authentication, obtained after signing up and
        generating an API key.

````