> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpique.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Social Media URLs

> Submit social media video URLs for evaluation

## 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.

<Warning>
  **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](/api-docs/api-reference/evaluations/presigned-upload) instead.
</Warning>

## Request Body

<ParamField body="judge_id" type="string" required>
  The ID of the judge to use for evaluation. Must be a video-type judge.
</ParamField>

<ParamField body="video_urls" type="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.
</ParamField>

<ParamField body="webhook_url" type="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.
</ParamField>

## Request Example

### cURL

```bash theme={null}
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

```json theme={null}
{
  "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

<ResponseField name="batch_id" type="string">
  Unique identifier for this batch submission
</ResponseField>

<ResponseField name="jobs" type="array">
  Array of job information for each submitted video

  <Expandable title="Job Information">
    <ResponseField name="job_id" type="string">
      Unique identifier for this evaluation job
    </ResponseField>

    <ResponseField name="url" type="string">
      The original video URL submitted
    </ResponseField>

    <ResponseField name="status" type="string">
      Initial status of the job (will be `awaiting_upload`)
    </ResponseField>

    <ResponseField name="error_message" type="string">
      Error message if the job failed to create (null if successful)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total_videos" type="integer">
  Total number of videos submitted in this batch
</ResponseField>

<ResponseField name="webhook_id" type="string">
  ID of the webhook that will be used for notifications (if configured)
</ResponseField>

## Response Example

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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"{timestamp}.{raw_body}" (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