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.

​
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: 
{
  "job_id": "job_aB3cD4eF5gH6iJ7k",
  "batch_id": "batch_hJ8kLm3nP9qR2vXy",
  "status": "completed",
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "overall_score": 85.5,
  "results": [...],
  "completed_at": "2024-01-15T12:45:00Z"
}
The webhook request will include an X-Webhook-Signature header for request validation using HMAC-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