Please log in to access your API credentials and start using our APIs. Log In & Start Free Trial

Social Account Validator API

Render a social profile or post, capture a screenshot, and classify whether the target appears public, gated, restricted, not found, or unclear.

API Endpoint

https://api.nyne.ai/person/social-account-validator

Overview

Use this API when you need proof that a social account or post was visible at validation time. The API returns a persistent screenshot URL and structured classification metadata.

Platforms: Instagram, X, Facebook, and LinkedIn
Inputs: full URL, or platform plus handle for profiles
Targets: profiles and posts
Output: screenshot URL, status, confidence, evidence, and account activity signal

Authentication

All requests require your API key and secret in headers.

Header Authentication

X-API-Key: your_api_key_here
X-API-Secret: your_api_secret_here

Credit Usage

Credits are charged after a target is successfully rendered and a screenshot is persisted.

Social Account Validator: 10 credits per successfully rendered target
Batch requests: charged per completed target
Provider or internal render failures: not charged

POST /person/social-account-validator

Queue validation for one social target.

POST /person/social-account-validator

Parameters

url (string, optional)
Full profile or post URL. Required unless using platform plus handle.

platform (string, optional)
instagram, x, facebook, or linkedin. Required when using handle.

handle (string, optional)
Profile handle or platform path. Post validation requires a full URL.

target_type (string, optional)
auto, profile, or post. Default: auto.

callback_url (string, optional)
Webhook URL for the final result.

Request Example

{ "platform": "instagram", "handle": "nasa", "target_type": "profile" }

Queued Response

{ "success": true, "data": { "request_id": "sav_abc123...", "status": "queued" } }

POST /person/social-account-validator/batch

Queue up to 25 social targets in one parent request.

POST /person/social-account-validator/batch

Request Example

{ "targets": [ { "platform": "instagram", "handle": "nasa" }, { "url": "https://x.com/NASA/status/2041707173428748594", "target_type": "post" } ], "callback_url": "https://yourapp.com/webhooks/social-account-validator" }

GET /person/social-account-validator

Poll with the returned request ID until the request is completed or failed.

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

Completed Response Example

{ "success": true, "data": { "request_id": "sav_abc123...", "status": "completed", "platform": "instagram", "target_type": "profile", "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", "evidence": [ "Handle or target path appears in rendered text/metadata." ], "credits_charged": 10 } }

Validation Statuses

visible_public_profile
visible_profile_with_login_prompt
visible_public_post
visible_post_with_login_prompt
login_wall_or_consent_only
private_or_restricted
not_found
unclear_profile_possible
unclear_screenshot_captured
unclear_no_screenshot

Callbacks

If callback_url is provided, the API sends the final single or batch payload after processing finishes. Your endpoint should return HTTP 2xx.

Error Codes

HTTP	Code	Description
400	`missing_parameters`	Missing URL or platform plus handle.
400	`invalid_request_id`	The request ID format is invalid.
400	`unsupported_platform`	The URL or platform is not supported.
401	`invalid_credentials`	API key or secret is incorrect.
402	`insufficient_credits`	Not enough credits for the requested targets.
404	`request_not_found`	The request ID was not found for this API key.
429	`rate_limit_exceeded`	Too many requests for the current key.
503	`service_unavailable`	The API or renderer is temporarily unavailable.