Skip to main content
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.