Documentation

Data Export API Reference

Browse processing history, export results to CSV/JSON/JSONL, and access stored images

Data API Overview

The Data API provides access to your processing history (descriptions and verifications), bulk export capabilities, and image retrieval endpoints. All endpoints are prefixed with/api/v2/data and require authentication. Image endpoints return redirects to presigned URLs with 1-hour expiry for secure CDN delivery.

Processing History

GET/api/v2/data/descriptions

Get paginated history of image descriptions with filtering and search

Request

// Query parameters:
?start_date=2025-01-01T00:00:00Z   // Filter by start date (ISO format)
&end_date=2025-01-31T23:59:59Z     // Filter by end date (ISO format)
&min_confidence=0.8                 // Minimum confidence score (0-1)
&max_confidence=1.0                 // Maximum confidence score (0-1)
&search=landscape,mountain          // Search terms (comma-separated)
&source_types=single,batch          // Source types (comma-separated)
&offset=0                           // Results to skip (default: 0)
&limit=100                          // Max results to return (1-1000, default: 100)

Response

{
  "results": [
    {
      "id": "desc_001",
      "type": "description",
      "source_type": "single",
      "source_id": "op_abc123",
      "created_at": "2025-01-15T10:30:00Z",
      "image_url": "https://example.com/image.jpg",
      "stored_image_url": "/api/v2/data/images/desc_001",
      "description": "A mountain landscape with snow-capped peaks...",
      "confidence_score": 0.92,
      "verification": null,
      "image_id": "img_xyz789",
      "thumbnail_url": "/api/v2/data/images/desc_001/thumbnail?size=small",
      "metadata": {}
    }
  ],
  "total_count": 1250,
  "statistics": {
    "total_count": 1250,
    "average_confidence": 0.89,
    "confidence_distribution": { "0.8-0.9": 450, "0.9-1.0": 800 },
    "providers_used": { "provider_a": 800, "provider_b": 450 },
    "daily_counts": [{ "date": "2025-01-15", "count": 42 }],
    "source_distribution": { "single": 500, "batch": 750 }
  },
  "filters_applied": {
    "date_range_applied": true,
    "confidence_range_applied": true,
    "search_applied": true,
    "source_types_filtered": false,
    "filter_summary": "Date: 2025-01-01 to 2025-01-31, Min confidence: 0.8"
  },
  "page_info": {
    "offset": 0,
    "limit": 100,
    "has_next": true,
    "has_previous": false,
    "total_pages": 13,
    "current_page": 1
  }
}

GET/api/v2/data/verifications

Get paginated history of image verifications with filtering and search

Request

// Query parameters:
?start_date=2025-01-01T00:00:00Z   // Filter by start date (ISO format)
&end_date=2025-01-31T23:59:59Z     // Filter by end date (ISO format)
&min_confidence=0.8                 // Minimum confidence score (0-1)
&max_confidence=1.0                 // Maximum confidence score (0-1)
&search=product,claim               // Search terms (comma-separated)
&source_types=single,batch          // Source types (comma-separated)
&offset=0                           // Results to skip (default: 0)
&limit=100                          // Max results to return (1-1000, default: 100)

Response

{
  "results": [
    {
      "id": "ver_001",
      "type": "verification",
      "source_type": "batch",
      "source_id": "batch_abc123",
      "created_at": "2025-01-15T11:00:00Z",
      "image_url": "https://example.com/product.jpg",
      "stored_image_url": "/api/v2/data/images/ver_001",
      "description": null,
      "confidence_score": 0.87,
      "verification": {
        "vlm_response": "The image shows a product matching the description...",
        "verified_claims": [
          { "claim": "Product is blue", "verified": true, "confidence": 0.95 }
        ],
        "issues_found": [
          { "issue": "Label text partially obscured", "severity": "low" }
        ],
        "hallucination_probability": 0.12,
        "rule_violations": []
      },
      "image_id": "img_def456",
      "thumbnail_url": "/api/v2/data/images/ver_001/thumbnail?size=small",
      "metadata": {}
    }
  ],
  "total_count": 830,
  "statistics": {
    "total_count": 830,
    "average_confidence": 0.85,
    "confidence_distribution": { "0.7-0.8": 200, "0.8-0.9": 400, "0.9-1.0": 230 },
    "providers_used": { "provider_a": 600, "provider_b": 230 },
    "daily_counts": [{ "date": "2025-01-15", "count": 28 }],
    "source_distribution": { "single": 300, "batch": 530 }
  },
  "filters_applied": {
    "date_range_applied": true,
    "confidence_range_applied": true,
    "search_applied": false,
    "source_types_filtered": false,
    "filter_summary": "Date: 2025-01-01 to 2025-01-31, Min confidence: 0.8"
  },
  "page_info": {
    "offset": 0,
    "limit": 100,
    "has_next": true,
    "has_previous": false,
    "total_pages": 9,
    "current_page": 1
  }
}

Data Export

POST/api/v2/data/export

Export processing results (descriptions or verifications) in CSV, JSON, or JSONL format. The operation is asynchronous -- returns immediately with an export ID.

Request

{
  "data_type": "descriptions",         // "descriptions" | "verifications"
  "format": "csv",                     // "csv" | "json" | "jsonl"
  "start_date": "2025-01-01T00:00:00Z",  // Optional: filter by start date
  "end_date": "2025-01-31T23:59:59Z",    // Optional: filter by end date
  "min_confidence": 0.8,              // Optional: minimum confidence (0-1)
  "max_confidence": 1.0,              // Optional: maximum confidence (0-1)
  "search_terms": ["safety", "equipment"],  // Optional: search terms array
  "source_types": ["single", "batch"],      // Optional: source type filter
  "include_metadata": true,            // Include metadata in export (default: true)
  "include_failed": false,             // Include failed results (default: false)
  "fields": ["id", "description", "confidence_score"],  // Optional: specific fields
  "limit": 10000                       // Optional: max records (up to 100000)
}

Response

// 202 Accepted
{
  "export_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "download_url": null,
  "record_count": null,
  "format": "csv",
  "created_at": "2025-01-15T10:30:00Z",
  "estimated_completion_time": "2025-01-15T10:31:00Z",
  "error_message": null
}

GET/api/v2/data/export/{export_id}

Check the status of an export operation. Returns download URL when completed. Download URLs expire after 1 hour.

Response

{
  "export_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "download_url": "https://storage.aionvision.tech/exports/...",
  "record_count": 1250,
  "format": "csv",
  "created_at": "2025-01-15T10:30:00Z",
  "estimated_completion_time": null,
  "error_message": null
}

// Possible status values: "pending", "processing", "completed", "failed"

// When failed:
{
  "export_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "download_url": null,
  "record_count": null,
  "format": "csv",
  "created_at": "2025-01-15T10:30:00Z",
  "estimated_completion_time": null,
  "error_message": "Export exceeded maximum record limit"
}

Image Access

GET/api/v2/data/images/{verification_id}

Retrieve a stored image by verification ID. By default redirects to the thumbnail endpoint for optimal performance. Set thumbnail=false for the full-size image.

Request

// Query parameters:
?thumbnail=true    // Redirect to thumbnail (default: true)
&size=small        // Thumbnail size: "tiny" | "small" | "medium" (default: "small")

Response

// 307 Temporary Redirect (default, thumbnail=true)
// Location: /api/v2/data/images/{verification_id}/thumbnail?size=small

// 501 Not Implemented (when thumbnail=false)
// Full image retrieval via this endpoint is temporarily unavailable.
// Use the /variant/original endpoint instead.

GET/api/v2/data/batch-images/{item_id}

Retrieve a stored image from a batch item by item ID. By default redirects to the thumbnail endpoint for optimal performance.

Request

// Query parameters:
?thumbnail=true    // Redirect to thumbnail (default: true)
&size=small        // Thumbnail size: "tiny" | "small" | "medium" (default: "small")

Response

// 307 Temporary Redirect (default, thumbnail=true)
// Location: /api/v2/data/batch-images/{item_id}/thumbnail?size=small

// 501 Not Implemented (when thumbnail=false)
// Full image retrieval via this endpoint is temporarily unavailable.
// Use thumbnail=true.

GET/api/v2/data/images/{verification_id}/variants

List all available size variants for a verification image. Returns variant metadata including dimensions, file size, and download URLs.

Response

{
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "image_hash": "abc123def456...",
  "variants_available": true,
  "variants": [
    {
      "type": "tiny_64",
      "width": 64,
      "height": 48,
      "size_bytes": 2048,
      "size_kb": 2.0,
      "quality": 80,
      "format": "jpeg",
      "url": "/api/v2/data/images/{verification_id}/variant/tiny_64"
    },
    {
      "type": "small_256",
      "width": 256,
      "height": 192,
      "size_bytes": 15360,
      "size_kb": 15.0,
      "quality": 85,
      "format": "jpeg",
      "url": "/api/v2/data/images/{verification_id}/variant/small_256"
    },
    {
      "type": "medium_750",
      "width": 750,
      "height": 562,
      "size_bytes": 102400,
      "size_kb": 100.0,
      "quality": 85,
      "format": "jpeg",
      "url": "/api/v2/data/images/{verification_id}/variant/medium_750"
    },
    {
      "type": "large_1024",
      "width": 1024,
      "height": 768,
      "size_bytes": 204800,
      "size_kb": 200.0,
      "quality": 90,
      "format": "jpeg",
      "url": "/api/v2/data/images/{verification_id}/variant/large_1024"
    },
    {
      "type": "original",
      "width": 4032,
      "height": 3024,
      "size_bytes": 2097152,
      "size_kb": 2048.0,
      "quality": null,
      "format": "jpeg",
      "url": "/api/v2/data/images/{verification_id}/variant/original"
    }
  ]
}

// When no image is associated:
{
  "verification_id": "550e8400-e29b-41d4-a716-446655440000",
  "variants_available": false,
  "variants": []
}

GET/api/v2/data/images/{verification_id}/variant/{variant_type}

Retrieve a specific size variant of a verification image. Returns a 302 redirect to a presigned URL with 1-hour caching.

Request

// Path parameter variant_type must be one of:
// "tiny_64"      - 64px max dimension
// "small_256"    - 256px max dimension
// "medium_750"   - 750px max dimension
// "large_1024"   - 1024px max dimension
// "original"     - Full resolution

Response

// 302 Found
// Location: https://storage.aionvision.tech/images/...?X-Amz-Signature=...
// Cache-Control: public, max-age=3600
// X-Image-Variant: medium_750

// 400 Bad Request (invalid variant type)
{
  "detail": "Invalid variant type. Must be one of: tiny_64, small_256, medium_750, large_1024, original"
}

// 404 Not Found
{
  "detail": "Verification {verification_id} not found"
}

GET/api/v2/data/images/{verification_id}/thumbnail

Convenience endpoint to get a thumbnail for a verification. Redirects to the appropriate image variant based on requested size.

Request

// Query parameters:
?size=small   // "tiny" (64px) | "small" (256px, default) | "medium" (750px)

Response

// 302 Found
// Location: https://storage.aionvision.tech/images/...?X-Amz-Signature=...
// Cache-Control: public, max-age=3600
// X-Image-Variant: small_256

// Size to variant mapping:
// tiny   -> tiny_64
// small  -> small_256
// medium -> medium_750

GET/api/v2/data/batch-images/{batch_item_id}/thumbnail

Get a thumbnail image for a batch item. Redirects to the appropriate image variant based on requested size.

Request

// Query parameters:
?size=small   // "tiny" (64px) | "small" (256px, default) | "medium" (750px)

Response

// 302 Found
// Location: https://storage.aionvision.tech/images/...?X-Amz-Signature=...
// Cache-Control: public, max-age=3600
// X-Image-Variant: small_256

// Size to variant mapping:
// tiny   -> tiny_64
// small  -> small_256
// medium -> medium_750

Datasets Reference

Dataset-based exports

Usage Reference

Usage analytics exports

Documentation

Data Export API Reference

Data API Overview

Processing History

Request

Response

Request

Response

Data Export

Request

Response

Response

Image Access

Request

Response

Request

Response

Response

Request

Response

Request

Response

Request

Response

Related

Datasets Reference

Usage Reference