# Social Account Validator API
> Validate a social account or post and return screenshot proof plus status classification
**Base URL:** `https://api.nyne.ai`
**Endpoint:** `https://api.nyne.ai/person/social-account-validator`

---

## Overview
The Social Account Validator API validates a public Instagram, X, Facebook, or LinkedIn profile or supported post URL, returns a screenshot URL with an invalidation timestamp, and includes a structured visibility classification with confidence and evidence.
## Authentication

All requests require header authentication:

```
X-API-Key: YOUR_API_KEY
X-API-Secret: YOUR_API_SECRET
```

## Rate Limits

| Limit | Value |
|-------|-------|
| Per Minute | 60 requests |
| Per Hour | 1000 requests |
| Monthly | Varies by plan |

### Response Headers

Responses from endpoints that perform rate-limit checks include both legacy and standard rate-limit headers:

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Active per-minute or per-hour limit |
| `X-RateLimit-Remaining` | Remaining requests in the active window |
| `X-RateLimit-Reset` | Unix timestamp when the active window resets |
| `RateLimit-Limit` | Active per-minute or per-hour limit |
| `RateLimit-Remaining` | Remaining requests in the active window |
| `RateLimit-Reset` | Seconds until the active window resets |
| `Retry-After` | Seconds to wait before retrying; present on HTTP `429` rate-limit responses |

Monthly quota responses include quota-specific headers when available:

| Header | Description |
|--------|-------------|
| `X-Quota-Limit` | Monthly request or credit limit |
| `X-Quota-Used` | Amount used in the current billing cycle |
| `X-Quota-Remaining` | Amount remaining in the current billing cycle |
| `X-Quota-Reset` | Unix timestamp when the current billing cycle resets |

## Credit Usage

- **Social Account Validator:** 10 credits per completed target with a screenshot URL
---

## POST /person/social-account-validatorQueue a social profile or supported post validation request.
### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | Full profile or supported post URL. Platform, handle, and target type are derived automatically. |
| `callback_url` | string | No | Webhook URL for the final result |

> **Required:** Provide a full profile or supported post URL.
### Request Examples

**Basic Request:**

```json
{
  "url": "https://www.instagram.com/nasa/"
}
```

### Code Examples

**cURL:**

```bash
curl -X POST https://api.nyne.ai/person/social-account-validator \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.instagram.com/nasa/"
  }'
```

### Response Codes

| Code | Description |
|------|-------------|
| 202 | Validation request accepted and queued |
| 400 | Invalid target, callback URL, or request body |
| 401 | Invalid API credentials |
| 402 | Insufficient credits |
| 429 | Rate limit exceeded |

### Response Example

```json
{
  "success": true,
  "data": {
    "request_id": "sav_abc123",
    "status": "queued",
    "message": "Social account validation request queued. Use GET /person/social-account-validator?request_id=... to check status."
  }
}
```

---

## GET /person/social-account-validator
Check the status of a request.

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `request_id` | string | Yes | The single request ID beginning with sav_ or batch ID beginning with savb_ |

### Request Example

```
GET /person/social-account-validator?request_id=sav_abc123
```

### Response Codes

| Code | Description |
|------|-------------|
| 200 | Final completed, failed, or partial batch status returned |
| 202 | Request is still queued or processing |
| 400 | Missing or invalid request_id |
| 401 | Invalid API credentials |
| 403 | Request belongs to another API key |
| 404 | Request ID not found |

### Response Example

```json
{
  "success": true,
  "data": {
    "request_id": "sav_abc123",
    "status": "completed",
    "platform": "instagram",
    "target_type": "profile",
    "handle": "nasa",
    "normalized_url": "https://www.instagram.com/nasa/",
    "validation_status": "visible_profile_with_login_prompt",
    "account_active": true,
    "confidence": 0.74,
    "primary_screenshot_url": "https://api.nyne.ai/social-account-validation-artifacts/sav_abc123/primary.png",
    "image_invalidated_at": "2026-05-05T12:00:00",
    "credits_charged": 10  }
}
```

---

## Response Format

All API responses follow a consistent JSON format. All fields in enrichment results are **optional** and only included when data is available:
- The initial POST response returns a request_id and status queued- Poll with request_id until the status is completed, failed, or partial_failed- Screenshot URLs are only present after a target is completed with a persisted artifact- image_invalidated_at indicates when the screenshot artifact expires- Credits are charged for completed targets with a screenshot URL
---

## Error Codes

| HTTP Code | Error Code | Description |
|-----------|------------|-------------|
| 400 | `missing_parameters` | Missing URL |
| 400 | `invalid_request_id` | The request ID format is invalid |
| 400 | `unsupported_platform` | The URL host is not supported |
| 401 | `invalid_credentials` | API key or secret is incorrect |
| 402 | `insufficient_credits` | Not enough credits available |
| 404 | `request_not_found` | Request ID not found |
| 429 | `rate_limit_exceeded` | Rate limit exceeded |
| 503 | `service_unavailable` | API temporarily unavailable |

---

## Callbacks

When you provide a `callback_url`, the API sends results to your endpoint via HTTP POST.

### Retry Policy- Callbacks are queued after the single request or full batch reaches a final status- Your callback endpoint should return HTTP 2xx- The callback payload matches the final status response
Your callback endpoint should respond with HTTP 200-299. Any other code triggers a retry.

### Callback Payload Example

```json
{
  "request_id": "sav_abc123",
  "status": "completed",
  "payload": {
    "status": "completed",
    "primary_screenshot_url": "https://api.nyne.ai/social-account-validation-artifacts/sav_abc123/primary.png",
    "image_invalidated_at": "2026-05-05T12:00:00"
  }
}
```

---

## Related APIs
- **Social Profiles API** — Find social profiles associated with a person → `https://api.nyne.ai/documentation/person/social-profiles`
- **Social Newsfeed API** — Retrieve recent social posts for known people → `https://api.nyne.ai/documentation/person/newsfeed`