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

# client.predictions

> Manage predictions with the VLM Run Node.js SDK

# Predictions API

The `client.predictions` component provides methods to retrieve, list, and manage predictions across all content types. This is the central hub for tracking the status of all processing jobs in the platform.

## Quick Examples

### Get a Prediction

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
import { VlmRun } from "vlmrun";

const client = new VlmRun({
  apiKey: "your-api-key",
});

// Retrieve a specific prediction by ID
const prediction = await client.predictions.get("pred_abc123");
console.log(`Status: ${prediction.status}`);
```

### List Predictions

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
// List recent predictions
const predictions = await client.predictions.list({ limit: 10 });
for (const pred of predictions) {
  console.log(`${pred.id}: ${pred.status}`);
}
```

### Wait for Completion

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
// Wait for a prediction to complete
const completed = await client.predictions.wait(
  "pred_abc123",
  60,  // Maximum wait time in seconds
  1    // Check interval in seconds
);
console.log(`Completed at: ${completed.completed_at}`);
```

## Core Operations

### Retrieving Predictions

Get details about a specific prediction:

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
import { VlmRun } from "vlmrun";
import type { PredictionResponse } from "vlmrun";

const client = new VlmRun({
  apiKey: "your-api-key",
});

// Get prediction by ID
const prediction: PredictionResponse = await client.predictions.get("pred_abc123");

// Access prediction properties
console.log(`ID: ${prediction.id}`);
console.log(`Status: ${prediction.status}`);
console.log(`Created: ${prediction.created_at}`);

// If completed, access the structured response
if (prediction.status === "completed" && prediction.response) {
  console.log(`Result: ${JSON.stringify(prediction.response)}`);
}
```

### Listing Predictions

List predictions you've created (with pagination):

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
import { VlmRun } from "vlmrun";

const client = new VlmRun({
  apiKey: "your-api-key",
});

// Basic listing with default pagination
const predictions = await client.predictions.list();

// Custom pagination
const paginatedPredictions = await client.predictions.list({
  skip: 0,   // Skip this many items
  limit: 10  // Return at most this many items
});

// Process the list
for (const prediction of paginatedPredictions) {
  console.log(`ID: ${prediction.id}, Status: ${prediction.status}`);
}
```

### Waiting for Completion

Wait for long-running predictions to complete:

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
import { VlmRun } from "vlmrun";

const client = new VlmRun({
  apiKey: "your-api-key",
});

// Wait with default settings (60 seconds timeout, 1 second checks)
const completed = await client.predictions.wait("pred_abc123");

// Wait with custom timeout and polling interval
const completedCustom = await client.predictions.wait(
  "pred_abc123",
  300,  // Maximum wait time (5 minutes)
  2     // Check every 2 seconds
);

// Check results after waiting
if (completedCustom.status === "completed") {
  console.log(`Success! Result: ${JSON.stringify(completedCustom.response)}`);
} else {
  console.log(`Failed or timed out: ${completedCustom.status}`);
}
```

The `wait()` method will throw a `TimeoutError` if the prediction doesn't complete within the specified timeout.

## Prediction Statuses

Predictions can have the following statuses:

| Status      | Description                                |
| ----------- | ------------------------------------------ |
| `enqueued`  | The prediction is waiting to be processed  |
| `pending`   | The prediction is preparing to start       |
| `running`   | The prediction is actively being processed |
| `completed` | The prediction has completed successfully  |
| `failed`    | The prediction encountered an error        |
| `paused`    | The prediction has been paused             |

## Feedback Operations

### Get Feedbacks for a Prediction

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
import { VlmRun } from "vlmrun";

const client = new VlmRun({
  apiKey: "your-api-key",
});

// Get all feedbacks for a prediction
const feedbacks = await client.predictions.getFeedbacks("pred_abc123");
for (const feedback of feedbacks) {
  console.log(`Feedback ID: ${feedback.id}`);
  console.log(`Notes: ${feedback.notes}`);
}
```

### Create Feedback

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
import { VlmRun } from "vlmrun";

const client = new VlmRun({
  apiKey: "your-api-key",
});

// Create feedback for a prediction
const feedback = await client.predictions.createFeedback({
  request_id: "pred_abc123",
  response: { corrected_field: "new_value" },
  notes: "Corrected the invoice number",
});

console.log(`Feedback created: ${feedback.id}`);
```

## Media-Specific APIs

The base `Predictions` class is extended by specialized prediction classes for different media types:

### Image Predictions

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
// Generate prediction from image files
const prediction = await client.image.generate({
  images: ["path/to/image.jpg"],  // Local file paths or base64 strings
  domain: "document.invoice"
});

// Generate prediction from image URLs
const predictionFromUrl = await client.image.generate({
  urls: ["https://example.com/image.jpg"],
  domain: "document.invoice"
});

// Generate schema from image
const schema = await client.image.schema({
  images: ["path/to/image.jpg"]
});
```

### Document, Audio, and Video Predictions

These specialized APIs follow a consistent pattern:

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
// Process a document file
const docPrediction = await client.document.generate({
  fileId: "file_abc123",
  domain: "document.invoice"
});

// Process from a URL
const audioPrediction = await client.audio.generate({
  url: "https://example.com/audio.mp3",
  domain: "audio.transcription"
});

// Process video
const videoPrediction = await client.video.generate({
  fileId: "file_xyz789",
  domain: "video.transcription"
});
```

## Response Structure

The `PredictionResponse` object includes these key fields:

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
interface PredictionResponse {
  id: string;                    // Unique prediction identifier
  status: JobStatus;             // Current job status
  created_at: string;            // When the prediction was created
  completed_at?: string;         // When the prediction was completed (if done)
  response?: any;                // Structured result data
  message?: string;              // Status message or error details
  usage?: CreditUsage;           // Usage and billing information
}
```

The `usage` field contains a `CreditUsage` object:

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
interface CreditUsage {
  elements_processed?: number;   // Number of elements processed
  element_type?: "image" | "page" | "video" | "audio";  // Type of element
  credits_used?: number;         // Credits consumed by the operation
}
```

## Common Patterns

### Process and Wait

A common pattern is to start a prediction and wait for it to complete:

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
import { VlmRun } from "vlmrun";

const client = new VlmRun({
  apiKey: "your-api-key",
});

// 1. Start the prediction
const prediction = await client.document.generate({
  fileId: "file_abc123",
  domain: "document.invoice"
});

// 2. Wait for completion if needed
let result = prediction;
if (prediction.status !== "completed") {
  try {
    result = await client.predictions.wait(
      prediction.id,
      120  // Wait up to 2 minutes
    );
  } catch (error) {
    console.log("Processing is taking longer than expected");
    // Handle timeout case
  }
}

// 3. Process the results
if (result.status === "completed") {
  const formData = result.response;
  console.log(`Form data: ${JSON.stringify(formData)}`);
}
```

### Batch Processing

For batch operations, use the batch parameter and track multiple predictions:

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
import { VlmRun } from "vlmrun";

const client = new VlmRun({
  apiKey: "your-api-key",
});

// Start multiple predictions in batch mode
const predictionIds: string[] = [];
const fileIds = ["file_1", "file_2", "file_3"];

for (const fileId of fileIds) {
  const prediction = await client.document.generate({
    fileId,
    domain: "document.invoice",
    batch: true  // Process asynchronously
  });
  predictionIds.push(prediction.id);
}

console.log(`Started ${predictionIds.length} predictions`);

// Wait for all to complete
const results = await Promise.all(
  predictionIds.map(id => client.predictions.wait(id, 300))
);

console.log("All predictions complete!");
```

### Error Handling

Implement robust error handling:

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
import { VlmRun, ApiError } from "vlmrun";

const client = new VlmRun({
  apiKey: "your-api-key",
});

try {
  // Start prediction
  const prediction = await client.document.generate({
    fileId: "file_abc123",
    domain: "document.invoice"
  });

  // Wait for completion
  const result = await client.predictions.wait(prediction.id);

  // Check for success
  if (result.status === "completed") {
    console.log("Processing successful!");
    console.log(result.response);
  } else {
    console.log(`Processing failed: ${result.status}`);
    console.log(`Message: ${result.message}`);
  }

} catch (error) {
  if (error instanceof ApiError) {
    console.error(`API Error: ${error.message}`);
    console.error(`Status: ${error.http_status}`);
  } else if (error instanceof Error && error.name === "TimeoutError") {
    console.error("Prediction timed out");
  } else {
    console.error(`Unexpected error: ${error}`);
  }
}
```

## TypeScript Interfaces

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
interface ListParams {
  skip?: number;
  limit?: number;
}

interface FeedbackParams {
  request_id: string;
  response?: Record<string, any>;
  notes?: string;
}

interface FeedbackResponse {
  id: string;
  created_at: string;
  request_id: string;
  response: any;
  notes?: string;
}
```

## Best Practices

### Efficient Polling

Use appropriate intervals when waiting for predictions:

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
// For quick predictions (e.g., simple image classification)
const quickResult = await client.predictions.wait(
  predictionId,
  30,  // 30 seconds
  1    // Check every second
);

// For complex processing (e.g., large documents, long videos)
const complexResult = await client.predictions.wait(
  predictionId,
  600,  // 10 minutes
  5     // Check every 5 seconds
);
```

### Using Callbacks for Long-Running Jobs

For very long-running predictions, consider using callback URLs:

```typescript theme={"theme":{"light":"github-light","dark":"dark-plus"}}
const prediction = await client.video.generate({
  fileId: "file_abc123",
  domain: "video.transcription",
  batch: true,
  callbackUrl: "https://your-server.com/webhook/predictions"
});

// Your webhook will receive the completed prediction
console.log(`Prediction started: ${prediction.id}`);
```