Skip to main content
NVIDIA

nvidia/Kumo Relational

Endpoint Details

Review how to make this request and handle its possible responses.

POSThttps://ai.api.nvidia.com/v1/structured-data/nvidia/kumo-relational/predictions

Accepts labeled context examples and the entity to score across one or more related tables in the Universal TFM request envelope. Predictive queries are compiled into this request by the NVIDIA Kumo Predict SDK; the original query is preserved in metadata.source_query.

Request Body

Edit the request fields below.

schema*
instance table*
One or more primary key columns. Kumo Relational requires the instance table primary key to be instance_id, and every related table to include an instance_id column.
Related table schemas keyed by table name (entity and fact tables).
relationshipsRelationships linking the instance, entity, and fact tables.
context*
instance table*Table payload descriptor. Arrays are the supported table payload format.
columns*Column order for arrays-format rows.
rows*Arrays-format table rows. Each row follows the order in columns.
Related table payloads keyed by table name (entity and fact tables).
predict*
instance table*Table payload descriptor. Arrays are the supported table payload format.
columns*Column order for arrays-format rows.
rows*Arrays-format table rows. Each row follows the order in columns.
Related table payloads keyed by table name (entity and fact tables).
Authentication uses NVIDIA_API_KEY from your environment.

Request details

Parameters8 Parameters
Body parametersRequest parameters that update the generated request preview.
object
modelrequired
string · enum

TFM model family requested by the caller.

Valid values: kumo-relational
taskrequired
object
schemarequired
object
schema*
instance table*
One or more primary key columns. Kumo Relational requires the instance table primary key to be instance_id, and every related table to include an instance_id column.
Related table schemas keyed by table name (entity and fact tables).
relationshipsRelationships linking the instance, entity, and fact tables.
contextrequired
object
context*
instance table*Table payload descriptor. Arrays are the supported table payload format.
columns*Column order for arrays-format rows.
rows*Arrays-format table rows. Each row follows the order in columns.
Related table payloads keyed by table name (entity and fact tables).
predictrequired
object
predict*
instance table*Table payload descriptor. Arrays are the supported table payload format.
columns*Column order for arrays-format rows.
rows*Arrays-format table rows. Each row follows the order in columns.
Related table payloads keyed by table name (entity and fact tables).
outputrequired
object
inferenceoptional
object
metadataoptional
object
Headers3 Headers
Request headersAuthentication and content negotiation values for this request.
object
Authorizationrequired
Bearer credential used to authenticate the request.

Format: Bearer $NVIDIA_API_KEY

Content-Typerequired
Identifies the request body as JSON.
Acceptoptional
Selects the desired response content type.

Request preview

Updates as you change request parameters and headers on the left.

import json

import requests


payload = {
    "model": "kumo-relational",
    "task": {
        "kind": "binary_classification",
        "target": {
            "column_name": "label",
            "dtype": "bool",
            "classes": ["false", "true"],
            "positive_class": "true",
        },
        "entity_table_names": ["accounts"],
        "anchor_time_column": "anchor_time",
    },
    "schema": {
        "instance_table": {
            "columns": {
                "instance_id": {
                    "dtype": "int64",
                    "stype": "ID",
                    "nullable": False,
                },
                "anchor_time": {
                    "dtype": "timestamp[us]",
                    "stype": "timestamp",
                    "nullable": False,
                },
                "account_id": {
                    "dtype": "int64",
                    "stype": "ID",
                    "nullable": False,
                },
                "label": {
                    "dtype": "bool",
                    "stype": "categorical",
                },
            },
            "primary_key": "instance_id",
        },
        "related_tables": {
            "accounts": {
                "columns": {
                    "instance_id": {
                        "dtype": "int64",
                        "stype": "ID",
                        "nullable": False,
                    },
                    "account_id": {
                        "dtype": "int64",
                        "stype": "ID",
                        "nullable": False,
                    },
                    "amount": {
                        "dtype": "float64",
                        "stype": "numerical",
                    },
                    "segment": {
                        "dtype": "string",
                        "stype": "categorical",
                    },
                },
                "primary_key": ["instance_id", "account_id"],
            }
        },
        "relationships": [
            {
                "source_columns": ["instance_id", "account_id"],
                "target_table": "accounts",
                "target_columns": ["instance_id", "account_id"],
            }
        ],
    },
    "context": {
        "instance_table": {
            "format": "arrays",
            "columns": ["instance_id", "anchor_time", "account_id", "label"],
            "rows": [
                [0, "2025-01-01T00:00:00Z", 100, False],
                [1, "2025-01-01T00:00:00Z", 101, True],
                [2, "2025-01-02T00:00:00Z", 102, False],
                [3, "2025-01-02T00:00:00Z", 103, True],
            ],
        },
        "related_tables": {
            "accounts": {
                "format": "arrays",
                "columns": ["instance_id", "account_id", "amount", "segment"],
                "rows": [
                    [0, 100, 10.5, "small"],
                    [1, 101, 250.0, "enterprise"],
                    [2, 102, 12.0, "small"],
                    [3, 103, 300.0, "enterprise"],
                ],
            }
        },
    },
    "predict": {
        "instance_table": {
            "format": "arrays",
            "columns": ["instance_id", "anchor_time", "account_id"],
            "rows": [[4, "2025-02-01T00:00:00Z", 104]],
        },
        "related_tables": {
            "accounts": {
                "format": "arrays",
                "columns": ["instance_id", "account_id", "amount", "segment"],
                "rows": [[4, 104, 275.0, "enterprise"]],
            }
        },
    },
    "output": {"fields": ["prediction", "probabilities"]},
}

response = requests.post(
    "https://ai.api.nvidia.com/v1/structured-data/nvidia/kumo-relational/predictions",
    headers={
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer $NVIDIA_API_KEY",
    },
    json=payload,
)
response.raise_for_status()

print(json.dumps(response.json(), indent=2))

Responses

See example responses, schemas, and errors your integration should handle.

200Prediction responseapplication/json
Response bodyapplication/jsonobject

Example response

application/json
{
  "id": "pred_kumo_relational_001",
  "model": "kumo-relational",
  "predictions": [
    {
      "id": "9",
      "row_index": 0,
      "prediction": "true",
      "probabilities": {
        "false": 0.18,
        "true": 0.82
      }
    }
  ],
  "metadata": {
    "task_kind": "classification",
    "output_type": "probabilities"
  }
}
idrequired
string
modelrequired
string
predictionsrequired
array<object>
predictions[].idoptional
string
predictions[].row_indexrequired
integer
Minimum: 0
predictions[].predictionoptional
string | number | integer | boolean | null
predictions[].probabilitiesoptional
object
predictions[].scoresoptional
array<number>
predictions[].rankingsoptional
array<object>
predictions[].rankings[].idrequired
string
predictions[].rankings[].scorerequired
number
predictions[].embeddingsoptional
array<number>
predictions[].quantilesoptional
object
predictions[].explanationoptional
object
Minimum properties: 2
predictions[].explanation.formatrequired
string

Discriminator naming the model-defined explanation shape.

predictions[].metadataoptional
object
metadatarequired
object
metadata.task_kindrequired
string
metadata.output_typeoptional
string
metadata.adapteroptional
string
metadata.normalized_request_kindoptional
string
metadata.stub_backendoptional
boolean
400Problem details for a failed requestapplication/problem+json
Response bodyapplication/problem+jsonobject
typerequired
string

URI identifying the problem type.

Format: uri-reference
statusrequired
integer

HTTP status code for this occurrence of the problem.

Minimum: 100Maximum: 599
titlerequired
string

Short, human-readable summary of the problem.

detailrequired
string

Human-readable explanation specific to this occurrence.

coderequired
string

Stable application-specific code identifying the precise failure.

Maximum length: 1024
instanceoptional
string

URI identifying this specific problem occurrence.

Format: uri-reference
413Problem details for a failed requestapplication/problem+json
Response bodyapplication/problem+jsonobject
typerequired
string

URI identifying the problem type.

Format: uri-reference
statusrequired
integer

HTTP status code for this occurrence of the problem.

Minimum: 100Maximum: 599
titlerequired
string

Short, human-readable summary of the problem.

detailrequired
string

Human-readable explanation specific to this occurrence.

coderequired
string

Stable application-specific code identifying the precise failure.

Maximum length: 1024
instanceoptional
string

URI identifying this specific problem occurrence.

Format: uri-reference
415Problem details for a failed requestapplication/problem+json
Response bodyapplication/problem+jsonobject
typerequired
string

URI identifying the problem type.

Format: uri-reference
statusrequired
integer

HTTP status code for this occurrence of the problem.

Minimum: 100Maximum: 599
titlerequired
string

Short, human-readable summary of the problem.

detailrequired
string

Human-readable explanation specific to this occurrence.

coderequired
string

Stable application-specific code identifying the precise failure.

Maximum length: 1024
instanceoptional
string

URI identifying this specific problem occurrence.

Format: uri-reference
422Problem details for a failed requestapplication/problem+json
Response bodyapplication/problem+jsonobject
typerequired
string

URI identifying the problem type.

Format: uri-reference
statusrequired
integer

HTTP status code for this occurrence of the problem.

Minimum: 100Maximum: 599
titlerequired
string

Short, human-readable summary of the problem.

detailrequired
string

Human-readable explanation specific to this occurrence.

coderequired
string

Stable application-specific code identifying the precise failure.

Maximum length: 1024
instanceoptional
string

URI identifying this specific problem occurrence.

Format: uri-reference
429Problem details for a failed requestapplication/problem+json
Response bodyapplication/problem+jsonobject
typerequired
string

URI identifying the problem type.

Format: uri-reference
statusrequired
integer

HTTP status code for this occurrence of the problem.

Minimum: 100Maximum: 599
titlerequired
string

Short, human-readable summary of the problem.

detailrequired
string

Human-readable explanation specific to this occurrence.

coderequired
string

Stable application-specific code identifying the precise failure.

Maximum length: 1024
instanceoptional
string

URI identifying this specific problem occurrence.

Format: uri-reference
500Problem details for a failed requestapplication/problem+json
Response bodyapplication/problem+jsonobject
typerequired
string

URI identifying the problem type.

Format: uri-reference
statusrequired
integer

HTTP status code for this occurrence of the problem.

Minimum: 100Maximum: 599
titlerequired
string

Short, human-readable summary of the problem.

detailrequired
string

Human-readable explanation specific to this occurrence.

coderequired
string

Stable application-specific code identifying the precise failure.

Maximum length: 1024
instanceoptional
string

URI identifying this specific problem occurrence.

Format: uri-reference
503Problem details for a failed requestapplication/problem+json
Response bodyapplication/problem+jsonobject
typerequired
string

URI identifying the problem type.

Format: uri-reference
statusrequired
integer

HTTP status code for this occurrence of the problem.

Minimum: 100Maximum: 599
titlerequired
string

Short, human-readable summary of the problem.

detailrequired
string

Human-readable explanation specific to this occurrence.

coderequired
string

Stable application-specific code identifying the precise failure.

Maximum length: 1024
instanceoptional
string

URI identifying this specific problem occurrence.

Format: uri-reference