Execute Endpoint Asynchronously

Execute your serverless endpoint asynchronously for long-running tasks, batch processing, or when you need to decouple request submission from result retrieval. This is ideal for tasks that take more than a few seconds to complete.

Path Parameters

endpointId: The unique identifier of the endpoint to execute

Request Body

{
    "input": {
        "prompt": "Generate a detailed 10-page report on climate change impacts",
        "format": "pdf",
        "citations": true,
        "sections": ["introduction", "impacts", "solutions", "conclusion"]
    },
    "async": true,
    "callbackUrl": "https://your-app.com/webhooks/job-complete",
    "priority": "normal",
    "tags": {
        "userId": "user_12345",
        "projectId": "proj_report_gen",
        "category": "document_generation"
    }
}

Example Usage

Long-Running Document Generation

curl -X POST "https://api.tensorone.ai/v2/endpoints/ep_document_gen/runasync" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "prompt": "Create a comprehensive business plan for a tech startup",
      "pages": 50,
      "include_financials": true,
      "industry": "artificial_intelligence"
    },
    "async": true,
    "callbackUrl": "https://myapp.com/webhooks/document-ready"
  }'

Batch Image Processing

curl -X POST "https://api.tensorone.ai/v2/endpoints/ep_image_processor/runasync" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "images": [
        "https://example.com/image1.jpg",
        "https://example.com/image2.jpg",
        "https://example.com/image3.jpg"
      ],
      "operations": ["resize", "enhance", "watermark"],
      "output_format": "webp"
    },
    "async": true,
    "priority": "high",
    "tags": {
      "batch_id": "batch_20240115_001",
      "user_id": "user_789"
    }
  }'

Video Processing with Progress Tracking

curl -X POST "https://api.tensorone.ai/v2/endpoints/ep_video_processor/runasync" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "video_url": "https://example.com/large-video.mp4",
      "operations": {
        "transcode": {
          "resolution": "1080p",
          "codec": "h264",
          "bitrate": "5000k"
        },
        "thumbnail": {
          "count": 10,
          "format": "jpg"
        }
      }
    },
    "async": true,
    "callbackUrl": "https://myapp.com/webhooks/video-processed",
    "priority": "normal"
  }'

Response

Returns a job object for tracking execution:

{
    "jobId": "job_1234567890abcdef",
    "status": "queued",
    "endpointId": "ep_document_gen",
    "priority": "normal",
    "estimatedDuration": 300,
    "createdAt": "2024-01-15T14:30:00Z",
    "statusUrl": "https://api.tensorone.ai/v2/jobs/job_1234567890abcdef/status",
    "tags": {
        "userId": "user_12345",
        "projectId": "proj_report_gen",
        "category": "document_generation"
    }
}

Job Status Tracking

Check Job Status

curl -X GET "https://api.tensorone.ai/v2/jobs/job_1234567890abcdef/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Status Response

{
    "jobId": "job_1234567890abcdef",
    "status": "running",
    "progress": 65,
    "startedAt": "2024-01-15T14:31:00Z",
    "estimatedCompletion": "2024-01-15T14:35:30Z",
    "currentStep": "generating_content",
    "metadata": {
        "pagesGenerated": 32,
        "totalPages": 50,
        "processingTime": 245
    }
}

Job Lifecycle

Status Values

queued: Job submitted and waiting for execution
running: Job is currently being processed
completed: Job finished successfully
failed: Job encountered an error
cancelled: Job was cancelled by user or system
timeout: Job exceeded maximum execution time

Progress Tracking

Jobs include progress information when available:

progress: Percentage completion (0-100)
currentStep: Current processing phase
estimatedCompletion: Predicted completion time
metadata: Task-specific progress details

Webhook Notifications

Callback Payload

When a job completes, your callback URL receives:

{
    "jobId": "job_1234567890abcdef",
    "status": "completed",
    "output": {
        "document_url": "https://storage.tensorone.ai/documents/report_abc123.pdf",
        "pages": 50,
        "word_count": 12500,
        "generation_time": 287
    },
    "executionTime": 287.5,
    "completedAt": "2024-01-15T14:34:47Z",
    "cost": 0.75,
    "tags": {
        "userId": "user_12345",
        "projectId": "proj_report_gen"
    }
}

Webhook Security

Verify webhook authenticity using the signature header:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Error Handling

422 Unprocessable Entity

{
    "error": "VALIDATION_ERROR",
    "message": "Invalid input parameters",
    "details": {
        "field": "input.pages",
        "value": -5,
        "reason": "Must be a positive integer"
    }
}

429 Too Many Requests

{
    "error": "QUEUE_FULL",
    "message": "Job queue is at capacity",
    "details": {
        "queueSize": 1000,
        "estimatedWait": 300,
        "retryAfter": 60
    }
}

507 Insufficient Storage

{
    "error": "STORAGE_LIMIT_EXCEEDED",
    "message": "Output size would exceed storage quota",
    "details": {
        "estimatedSize": "2.5GB",
        "remainingQuota": "1.2GB",
        "upgradeUrl": "https://app.tensorone.ai/upgrade"
    }
}

SDK Examples

Python SDK

from tensorone import TensorOneClient
import time

client = TensorOneClient(api_key="your_api_key")

# Submit async job
job = client.endpoints.execute_async(
    endpoint_id="ep_document_gen",
    input={
        "prompt": "Generate a technical whitepaper on quantum computing",
        "length": "long",
        "include_diagrams": True
    },
    callback_url="https://myapp.com/webhooks/job-complete",
    tags={"user_id": "user_123", "type": "whitepaper"}
)

print(f"Job submitted: {job.job_id}")

# Poll for completion
while True:
    status = client.jobs.get_status(job.job_id)
    print(f"Status: {status.status}, Progress: {status.progress}%")

    if status.status in ['completed', 'failed', 'cancelled']:
        break

    time.sleep(10)

if status.status == 'completed':
    print(f"Job completed! Output: {status.output}")
else:
    print(f"Job failed: {status.error}")

JavaScript SDK

import { TensorOneClient } from "@tensorone/sdk";

const client = new TensorOneClient({ apiKey: "your_api_key" });

// Submit async job with promise-based tracking
async function processLargeDataset() {
    const job = await client.endpoints.executeAsync("ep_data_processor", {
        input: {
            dataset_url: "https://example.com/large-dataset.csv",
            operations: ["clean", "analyze", "visualize"],
            output_format: "dashboard",
        },
        callbackUrl: "https://myapp.com/webhooks/analysis-complete",
        priority: "high",
    });

    console.log(`Job submitted: ${job.jobId}`);

    // Use async iterator for real-time updates
    for await (const update of client.jobs.watchStatus(job.jobId)) {
        console.log(`Progress: ${update.progress}% - ${update.currentStep}`);

        if (update.status === "completed") {
            console.log("Analysis complete!", update.output);
            break;
        }
    }
}

Use Cases

Document Generation

Reports: Generate comprehensive business or technical reports
Presentations: Create slide decks with dynamic content
Legal Documents: Generate contracts, agreements, and legal briefs

Media Processing

Video Transcoding: Convert videos to multiple formats and resolutions
Image Batch Processing: Apply effects, resize, or enhance multiple images
Audio Processing: Transcribe, enhance, or convert audio files

Data Analysis

Large Dataset Processing: Analyze CSV files, databases, or data streams
Machine Learning: Train models or run inference on large datasets
Report Generation: Create insights and visualizations from data

AI Model Inference

Batch Predictions: Run inference on large datasets
Model Fine-tuning: Customize models with your data
Multi-modal Processing: Combine text, image, and audio processing

Best Practices

Job Management

Tagging: Use tags to organize and filter jobs by user, project, or category
Priorities: Use high priority for time-sensitive tasks, normal for batch processing
Timeouts: Set appropriate timeouts based on expected processing time

Webhook Implementation

Idempotency: Handle duplicate webhook deliveries gracefully
Security: Always verify webhook signatures to prevent spoofing
Retry Logic: Implement exponential backoff for failed webhook deliveries

Performance Optimization

Batch Size: Group related tasks to reduce overhead
Input Optimization: Compress or optimize input data to reduce transfer time
Caching: Cache intermediate results when processing similar requests

Async jobs are queued and processed in order of submission and priority. High-priority jobs are processed before normal priority jobs.

Large output files are automatically stored in temporary storage and deleted after 7 days. Download results promptly or use your own storage.

Use webhooks instead of polling for better performance and reduced API usage. Set up retry logic for webhook deliveries.

Authorizations

Authorization

string

header

required

API key authentication. Use 'Bearer YOUR_API_KEY' format.

Path Parameters

endpointId

string

required

Unique identifier of the endpoint

Body

application/json

Input data for the endpoint execution

The body is of type object.

Response

Execution completed successfully

The response is of type object.

Getting Started

Account Management

GPU Clusters (VPS)

Serverless Endpoints

Managed Training

AI Services

Payment & Billing

Monitoring & Analytics

​Path Parameters

​Request Body

​Example Usage

​Long-Running Document Generation

​Batch Image Processing

​Video Processing with Progress Tracking

​Response

​Job Status Tracking

​Check Job Status

​Status Response

​Job Lifecycle

​Status Values

​Progress Tracking

​Webhook Notifications

​Callback Payload

​Webhook Security

​Error Handling

​422 Unprocessable Entity

​429 Too Many Requests

​507 Insufficient Storage

​SDK Examples

​Python SDK

​JavaScript SDK

​Use Cases

​Document Generation

​Media Processing

​Data Analysis

​AI Model Inference

​Best Practices

​Job Management

​Webhook Implementation

​Performance Optimization

Authorizations

Path Parameters

Body

Response

Path Parameters

Request Body

Example Usage

Long-Running Document Generation

Batch Image Processing

Video Processing with Progress Tracking

Response

Job Status Tracking

Check Job Status

Status Response

Job Lifecycle

Status Values

Progress Tracking

Webhook Notifications

Callback Payload

Webhook Security

Error Handling

422 Unprocessable Entity

429 Too Many Requests

507 Insufficient Storage

SDK Examples

Python SDK

JavaScript SDK

Use Cases

Document Generation

Media Processing

Data Analysis

AI Model Inference

Best Practices

Job Management

Webhook Implementation

Performance Optimization