This guide shows how to run inferences on installed Scientific AI Workflows using TetraScience AI Services versions 1.0.x.

Run an Inference

After you've installed Scientific AI Workflow and have its inference URL, you can run inferences programmatically by doing either of the following:

• Run an online (synchronous) inference to invoke the appropriate LLM, AI agent, or custom model to return real-time predictions from text-based inputs.
• Run an offline (asynchronous) inference to provide inputs through JSON files or specify datasets for batch predictions and asynchronous processing.

For AI workflows that require large files, such as model weights, configuration files, or reference data, you can also upload AI Workflow assets before running an inference.

Run an Online (Synchronous) Inference

Online (synchronous) inference performs real-time ML inference and returns results immediately. Use online inference for real-time predictions, chat and conversation workflows, and low-latency requirements (less than 60 seconds). For batch processing, large files, or long-running inference (more than 60 seconds), use an offline (asynchronous) inference instead.

📘

NOTE

Online inference is only available for AI workflows that have a Model Serving Endpoint configured.

Required Policies

To submit an online inference request, users must have one of the following policy permissions:

API Endpoint

POST /v1/inference/online

Request Headers

Request Body

Inference Options

Inference Input Formats

The inferenceInput field supports multiple formats, depending on the model serving endpoint requirements:

Request Examples

Tabular Data (Buffered Response)

{
  "aiWorkflow": "lead-clone-selection",
  "version": "v2.1.0",
  "inferenceInput": {
    "dataframe_records": [
      { "feature1": 1.5, "feature2": "category_a", "feature3": 42 },
      { "feature1": 2.3, "feature2": "category_b", "feature3": 37 }
    ]
  },
  "inferenceOptions": {
    "stream": false,
    "metrics": true,
    "timeout": 30000
  }
}

Chat Conversation (Streaming Response)

{
  "aiWorkflow": "coding-assistant",
  "version": "v1.0.0",
  "inferenceInput": {
    "messages": [
      { "role": "user", "content": "Write a Python function to calculate factorial" }
    ]
  },
  "inferenceOptions": {
    "stream": true,
    "timeout": 30000
  }
}

Image Analysis

{
  "aiWorkflow": "cell-image-analysis",
  "version": "v1.5.0",
  "inferenceInput": {
    "images": [
      { "b64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk..." }
    ]
  },
  "inferenceOptions": {
    "stream": false,
    "metrics": true
  }
}

Response

Buffered Response (JSON)

When stream is false (default), the response is returned as a complete JSON object:

Example Response (Tabular Predictions)

{
  "requestId": "sync_123e4567-e89b-12d3-a456-426614174000",
  "status": "success",
  "inferenceOutput": {
    "predictions": [0.85, 0.72]
  },
  "metrics": {
    "runDuration": 245,
    "executionDuration": 245
  },
  "timestamp": "2025-09-29T10:30:00Z"
}

Streaming Response (Server-Sent Events)

When stream is true, results are streamed as Server-Sent Events (SSE) with Content-Type: text/event-stream:

data: {"chunk": "partial result", "done": false}

data: {"chunk": "more content", "done": false}

data: [DONE]

Error Responses

Get Inference Metrics

To retrieve metrics for a completed online inference request:

GET /v1/inference/online/{requestId}/metrics

Path Parameters

Response

Example Metrics Response

{
  "requestId": "sync_123e4567-e89b-12d3-a456-426614174000",
  "aiWorkflow": "lead-clone-selection:v2.1.0",
  "organization": "acme-corp",
  "status": "success",
  "processingTime": 1245,
  "timestamp": "2025-09-29T10:30:00Z",
  "inputSize": 2048
}

Run an Offline (Asynchronous) Inference

Offline (asynchronous) inference submits file-based inference requests for batch processing. Use offline inference for processing large files or datasets, running batch inference jobs, tasks expected to take more than 60 seconds, and when files are already uploaded to the platform. For real-time predictions or low-latency requirements, use online (synchronous) inference instead.

📘

NOTE

Keep in mind the following when running offline inferences:

• Offline inference supports partial success, where optional files can fail without blocking the inference job. Critical files (primary data files) must succeed for inference to proceed.
• Offline inference can be automated using the ts-inference-protocol. Configure a file processing pipeline with this protocol to automatically trigger inference requests when new files are uploaded to the platform. The protocol accepts configuration for the inferenceUrl, aiWorkflow, and authentication token, and then automatically submits matching files for inference processing.

Required Policies

To submit an offline inference request, you must have one of the following policy permissions:

API Endpoint

POST /v1/inference

Request Headers

Request Body

Input File Object

Each file in the inputFiles array must include:

Request Examples

Basic Inference Request

{
  "aiWorkflow": "cell-analysis",
  "inputFiles": [
    {
      "fileUuid": "550e8400-e29b-41d4-a716-446655440000",
      "role": "file",
      "processingOrder": 1,
      "dependencies": []
    }
  ]
}

Multi-File Inference with Dependencies

{
  "aiWorkflow": "lead-clone-selection",
  "version": "v2.1.0",
  "inputFiles": [
    {
      "fileUuid": "550e8400-e29b-41d4-a716-446655440001",
      "role": "file",
      "processingOrder": 1,
      "dependencies": []
    },
    {
      "fileUuid": "550e8400-e29b-41d4-a716-446655440002",
      "role": "instructions",
      "processingOrder": 2,
      "dependencies": ["550e8400-e29b-41d4-a716-446655440001"]
    },
    {
      "fileUuid": "550e8400-e29b-41d4-a716-446655440003",
      "role": "parameters",
      "processingOrder": 3,
      "dependencies": []
    }
  ]
}

Response

The API returns immediately with a 202 Accepted status and provides a request ID for tracking progress.

Example Response (All Files Staged Successfully)

{
  "requestId": "req-20250929-abc123def456",
  "statusUrl": "/v1/inference/req-20250929-abc123def456"
}

Example Response (Partial Staging Success)

{
  "requestId": "req-20250929-abc123def456",
  "statusUrl": "/v1/inference/req-20250929-abc123def456",
  "partialSuccess": true,
  "stagingSummary": {
    "totalFiles": 3,
    "successfulFiles": 2,
    "failedFiles": 1,
    "criticalFailures": 0,
    "optionalFailures": 1,
    "warnings": ["Optional file failed to stage: metadata.json (Access denied)"]
  }
}

Error Responses

Get Inference Status

To check the status of an offline inference request:

GET /v1/inference/{inferenceId}/status

Path Parameters

Query Parameters

Response

Example Status Response (Processing)

{
  "requestId": "req-20250929-abc123def456",
  "status": "processing",
  "aiWorkflow": "cell-analysis",
  "organization": "acme-corp",
  "user": "user123",
  "createdAt": "2025-09-29T10:30:00Z",
  "updatedAt": "2025-09-29T10:35:00Z",
  "stagingLocation": {
    "bucket": "inference-staging-bucket",
    "prefix": "tenant=acme/org=acme-corp/2025/09/29/req-20250929-abc123def456/",
    "fullPath": "s3://inference-staging-bucket/tenant=acme/org=acme-corp/2025/09/29/req-20250929-abc123def456/"
  },
  "outputLocation": {
    "bucket": "inference-output-bucket",
    "prefix": "tenants/acme/orgs/acme_corp/schemas/ai_assets/2025/09/29/req-20250929-abc123def456/",
    "fullPath": "s3://inference-output-bucket/tenants/acme/orgs/acme_corp/schemas/ai_assets/2025/09/29/req-20250929-abc123def456/"
  }
}

Example Status Response (Completed)

{
  "requestId": "req-20250929-abc123def456",
  "status": "completed",
  "aiWorkflow": "cell-analysis",
  "organization": "acme-corp",
  "user": "user123",
  "createdAt": "2025-09-29T10:30:00Z",
  "updatedAt": "2025-09-29T10:45:00Z",
  "completedAt": "2025-09-29T10:45:00Z"
}

Upload AI Workflow Assets

Some AI workflows require large files, such as model weights, configuration files, or reference data to be uploaded in advance before inference can be performed. The Assets API provides endpoints for listing existing assets and uploading new files to an AI workflow's assets directory.

Use the Assets API when you need to do any of the following:

• Upload model weights or checkpoints for inference notebooks
• Provide configuration files that customize workflow behavior
• Store reference datasets used during inference
• Upload any large files that cannot be passed inline with inference requests

Required Policies

To manage AI workflow assets, users must have one of the following platform roles:

List Assets

Retrieve a hierarchical listing of files and folders in an AI workflow's assets directory:

GET /v1/assets

Request Headers

Query Parameters

Example Request

curl -X GET "https://api.tetrascience.com/v1/assets?namespace=common&aiWorkflow=cell-analysis&path=/models" \
  -H "x-org-slug: acme-corp" \
  -H "ts-auth-token: YOUR_JWT_TOKEN"

Example Response

{
  "name": "models",
  "type": "folder",
  "path": "/models",
  "children": [
    {
      "name": "weights.pkl",
      "type": "file",
      "path": "/models/weights.pkl",
      "size": 104857600,
      "lastModified": "2025-09-29T10:30:00.000Z"
    },
    {
      "name": "config.json",
      "type": "file",
      "path": "/models/config.json",
      "size": 1024,
      "lastModified": "2025-09-29T09:15:00.000Z"
    }
  ]
}

Upload Assets

Uploading files to an AI workflow's assets directory is a two-step process:

1. Get a presigned URL: Call the Assets API to get a presigned Amazon Simple Storage Service (Amazon S3) URL for uploading
2. Upload the file: Use the presigned URL to upload your file directly to Amazon S3.

Step 1: Get Presigned Upload URL

POST /v1/assets

Request Headers

Query Parameters

Example Request

curl -X POST "https://api.tetrascience.com/v1/assets?namespace=common&aiWorkflow=cell-analysis&path=/models&fileName=weights.pkl" \
  -H "x-org-slug: acme-corp" \
  -H "ts-auth-token: YOUR_JWT_TOKEN"

Example Response

{
  "url": "https://s3.amazonaws.com/ai-assets-bucket/path/to/weights.pkl?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Signature=...",
  "expiresIn": 86400
}

Step 2: Upload File to Presigned URL

Use the presigned URL from Step 1 to upload your file directly to Amazon S3:

curl -X PUT "$PRESIGNED_URL" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./weights.pkl

Complete Upload Example

The following example shows the complete two-step process for uploading a model weights file:

# Step 1: Get presigned URL
PRESIGNED_URL=$(curl -s -X POST "https://api.tetrascience.com/v1/assets?namespace=common&aiWorkflow=cell-analysis&path=/models&fileName=model_weights.pkl" \
  -H "x-org-slug: acme-corp" \
  -H "ts-auth-token: YOUR_JWT_TOKEN" | jq -r '.url')

# Step 2: Upload file using presigned URL
curl -X PUT "$PRESIGNED_URL" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./model_weights.pkl

Error Responses

Documentation Feedback

Do you have questions about our documentation or suggestions for how we can improve it? Start a discussion in TetraConnect Hub. For access, see Access the TetraConnect Hub.

📘

NOTE

Feedback isn't part of the official TetraScience product documentation. TetraScience doesn't warrant or make any guarantees about the feedback provided, including its accuracy, relevance, or reliability. All feedback is subject to the terms set forth in the TetraConnect Hub Community Guidelines.