Skip to main content
Social Media URLs
curl --request POST \
  --url https://api.getpique.ai/v1/evaluations/social-media \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "judge_id": "<string>",
  "video_urls": [
    {}
  ],
  "webhook_url": "<string>"
}
'
{
  "batch_id": "<string>",
  "jobs": [
    {
      "job_id": "<string>",
      "url": "<string>",
      "status": "<string>",
      "error_message": "<string>"
    }
  ],
  "total_videos": 123,
  "webhook_id": "<string>"
}

​
Authentication

Required: API Key authentication via X-API-Key header

​
Overview

This endpoint allows you to submit social media video URLs for evaluation. The system will automatically download the videos and process them through your specified judge.
Pilot Testing Only: This API is intended for pilot testing and is not recommended for production use. Social media video scraping is fragile and may fail due to platform changes, bot detection, or rate limiting. For production applications, use the direct upload API instead.

​
Request Body

​
judge_id
string
required
The ID of the judge to use for evaluation. Must be a video-type judge.
​
video_urls
array
required
List of social media video URLs to process.Constraints:
  • Minimum 1 URL
  • Maximum 20 URLs per request
  • Must be valid HTTP/HTTPS URLs
**Note: ** videos may fail to be evaluated due to bot detection from the hosting website. It is recommended to use the direct upload api whenever possible.
​
webhook_url
string
Optional webhook URL to override your organization’s default webhook.If provided, this URL will receive notifications for this batch. The webhook will still use your organization’s webhook secret for request signing.

​
Request Example

​
cURL

curl -X POST "https://api.getpique.ai/v1/evaluations/social-media" \
  -H "X-API-Key: pk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "judge_id": "judge_abc123",
    "video_urls": [
      "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "https://www.tiktok.com/@username/video/123456789",
      "https://www.instagram.com/reel/ABC123/"
    ]
  }'

​
JSON Body

{
  "judge_id": "judge_abc123",
  "video_urls": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "https://www.tiktok.com/@username/video/123456789",
    "https://www.instagram.com/reel/ABC123/"
  ]
}

​
Response

​
batch_id
string
Unique identifier for this batch submission
​
jobs
array
Array of job information for each submitted video
​
total_videos
integer
Total number of videos submitted in this batch
​
webhook_id
string
ID of the webhook that will be used for notifications (if configured)

​
Response Example

{
  "batch_id": "batch_hJ8kLm3nP9qR2vXy",
  "jobs": [
    {
      "job_id": "job_aB3cD4eF5gH6iJ7k",
      "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      "status": "awaiting_upload",
      "error_message": null
    },
    {
      "job_id": "job_lM8nO9pQ0rS1tU2v",
      "url": "https://www.tiktok.com/@username/video/123456789",
      "status": "awaiting_upload",
      "error_message": null
    },
    {
      "job_id": "job_wX3yZ4aB5cD6eF7g",
      "url": "https://www.instagram.com/reel/ABC123/",
      "status": "awaiting_upload",
      "error_message": null
    }
  ],
  "total_videos": 3,
  "webhook_id": "webhook_xyz789"
}

​
Status Codes

  • 202 Accepted - Request accepted and videos queued for processing
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Missing or invalid API key
  • 404 Not Found - Judge not found or not accessible
  • 500 Internal Server Error - Server error

​
Webhook Notifications

If configured, your webhook will receive a POST request when each video completes processing: Headers: 
X-Pique-Signature: t=1732654321,v1=5d41402abc4b2a76b9719d911017c592,alg=sha256
Content-Type: application/json
Completed Evaluation: 
{
  "evaluation_id": "a1922bbb-7264-4e2e-82f6-778702b05a30",
  "job_id": "job_AbC123XyZ456789",
  "content_id": "550e8400-e29b-41d4-a716-446655440000",
  "judge_id": "a1b2c3d4-e5f6-4789-9012-3456789abcde",
  "status": "completed",
  "overall_score": 0.85,
  "timestamp": "2025-11-12T23:16:08.526491Z",
  "results": [
    {
      "criterion_id": "848b9b59-2775-4303-8912-0a6ff40b6fd6",
      "detector_name": "video_specs",
      "pass_check": true,
      "score": 1,
      "rationale": "Video specs meet requirements: 576x1024 (9:16), 30.0fps, 38.0s",
      "metrics": {
        "video_specs": {
          "width": 576,
          "height": 1024,
          "aspect_ratio": "9:16",
          "fps": 30,
          "duration_sec": 38.033991,
          "audio_sample_rate": 44100
        }
      }
    }
  ]
}
Failed Evaluation: 
{
  "event": "evaluation.failed",
  "job_id": "job_3vp2mT7dJh5vhZmpk2G_yg",
  "status": "failed",
  "timestamp": "2025-11-12T23:16:08.526491Z",
  "error": "Failed to process video",
  "judge_id": "9e8ed8b4-e4ff-4137-9469-11181586a9e6"
}

​
Webhook Endpoint Implementation Guidelines

Expected Response: Your webhook endpoint should return a 200 OK response. Any other status code will be considered a failure and may trigger retries. Timeout: Webhook requests timeout after 10 seconds. Ensure your endpoint responds within this time. Retries: Pique will retry failed webhook deliveries with exponential backoff. Implement idempotent processing using the job_id. Signing:
  • Header: X-Pique-Signature: t=<unix timestamp seconds>,v1=<hex hmac>,alg=sha256
  • Message for signing: message = f”.” (UTF-8 bytes)
  • Algorithm: HMAC(secret, message, SHA256)

​
Rate Limits

  • Maximum 20 videos per request
  • Recommended: Batch multiple videos in a single request rather than making individual requests

​
Error Responses

​
400 Bad Request

  • Judge is not of type ‘video’
  • Invalid video URLs
  • Too many URLs (exceeds 20)
  • Empty URL list

​
401 Unauthorized

Missing or invalid API key

​
404 Not Found

Judge not found or not accessible by your organization

​
500 Internal Server Error

Failed to create evaluation jobs due to server error