API Referencev1.0.0

Scravio API Documentation

Build high-quality email lists from social media platforms. Programmatically create campaigns, validate emails, export leads, and manage credits.

Base URLhttps://api.scravio.com/api

Get API Key

Authentication

All API requests require an API key passed in the X-API-Key header. Your key starts with sk_live_.

Create and manage your API keys in the API Keys dashboard.

curl https://api.scravio.com/api/auth/me \
  -H "X-API-Key: sk_live_your_api_key"

Error Responses

When an API request fails, the response body contains a standard error object:

Error Response

{
  "message": "Validation failed",
  "code": "VALIDATION_ERROR",
  "errors": [
    {
      "param": "inputs.hashtag",
      "msg": "Hashtag is required for INSTAGRAM_HASHTAG campaigns",
      "location": "body"
    }
  ],
  "requestId": "req_abc123"
}

Status	Meaning
`400`	Bad Request — invalid parameters or request body
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — insufficient permissions
`404`	Not Found — resource does not exist or does not belong to you
`409`	Conflict — e.g. validation already running for this campaign
`429`	Too Many Requests — rate limit exceeded
`500`	Internal Server Error — unexpected failure, retry later

Rate Limits

Some endpoints have per-account or per-resource rate limits to ensure fair usage. When you exceed a rate limit, the API returns 429 Too Many Requests. Rate limits are noted in each endpoint's description.

Endpoint	Limit
`POST /campaigns/{id}/stop`	5 requests/min per campaign
`POST /campaigns/{id}/validate`	3 requests/min per campaign
`POST /validation-jobs/text`	3 requests/hour
`POST /list-exports`	5 requests/hour

API Overview

Account

1 endpoint

Retrieve your account profile and credit balance.

Campaigns

8 endpoints

Create and manage email scraping campaigns across 6 social platforms.

Validation

7 endpoints

Submit and manage standalone email validation jobs created from pasted email lists or uploaded CSV/TXT files. These jobs are separate from campaign validation, which is tracked on campaign objects.

Exports

3 endpoints

Create and download CSV/XLSX list exports from campaign leads.

Credits

1 endpoint

View your credit transaction history and balance changes.

Account

Retrieve your account profile and credit balance.

GET/auth/me

Get current account

Returns the authenticated user's account profile including current credit balance, email verification status, and subscription plan limits (concurrentCampaignLimit, scrapingSpeed).

Responses

200Account profile

Field	Type	Description
`id`	`string`	User ID
`email`	`string<email>`	Email address
`name`	`string`	Display name
`avatar`	`string`nullable	Avatar URL
`isVerified`	`boolean`	Whether email is verified
`shouldMaskEmail`	`boolean`	Whether emails are masked in lead responses
`credits`	`number`	Current credit balance
`concurrentCampaignLimit`	`integer`	Max concurrent campaigns allowed by subscription
`scrapingSpeed`	`string`	Scraping speed tier `slownormalfastultra_fast`
`createdAt`	`string<date-time>`	Account creation timestamp

Example

curl -X GET https://api.scravio.com/api/auth/me \
  -H "X-API-Key: sk_live_your_api_key"

Campaigns

Create and manage email scraping campaigns across 6 social platforms.

POST/campaigns/reserve-preview

Preview credit reservation

Returns the credit reservation estimate that should be reviewed before creating any supported campaign. Send the same type, inputs, targetEmails, maxCreditCap, and validation flags to POST /campaigns when launching. All new campaign previews use top-level targetEmails. The backend derives internal scan caps such as maxItemsToProcess and maxProfilesToScan. maxCreditCap is optional for all reserve-preview campaign types; when omitted, campaign creation defaults the cap to the recommended reservation. Use data.summary for customer-facing budget review UI.

Request Bodyrequired

application/json

Field	Type	Description
`type`required	`string`	Campaign type to estimate. `INSTAGRAM_HASHTAGINSTAGRAM_USER_FOLLOWERSINSTAGRAM_USER_FOLLOWINGINSTAGRAM_POST_LIKERSINSTAGRAM_POST_COMMENTERSINSTAGRAM_PROFILE_LISTINSTAGRAM_KEYWORD_SEARCHYOUTUBE_KEYWORD_SEARCHYOUTUBE_CHANNEL_SEARCHFACEBOOK_KEYWORD_SEARCHLINKEDIN_KEYWORD_SEARCHTWITTER_KEYWORD_SEARCHTIKTOK_KEYWORD_SEARCHTIKTOK_SEARCH_USERSTIKTOK_USER_FOLLOWERSTIKTOK_USER_FOLLOWINGTIKTOK_POST_COMMENTERSX_KEYWORD_SEARCHX_FOLLOWERSX_FOLLOWINGX_RETWEETSX_REPLIERS`
`inputs`required	`object`	Type-specific campaign inputs. Use the same shape as POST /campaigns.
`targetEmails`required	`integer`	Requested number of unique email leads. Required for all new campaign previews.(1–1,000,000)
`maxCreditCap`	`number`	Optional hard stop cap for any reserve-preview campaign type, including Instagram. If omitted on creation, the reserved credits become the cap.
`enableEmailValidation`	`boolean`	Include email validation usage in the estimateDefault: `false`
`enableDeepEmailSearch`	`boolean`	Include automatic deep email search when supportedDefault: `true for supported non-email-only types`

Responses

200Reserve preview

Field	Type	Description
`success`	`boolean`	Whether preview generation succeeded
`requestId`	`string`	Preview request identifier
`data`	`object`	Reserve preview data. Responses include a customer-facing summary plus targetEmails, internal scan caps such as emailCollectionGoal/maxItemsToProcess/maxProfilesToScan, maxCreditCap, estimatedCredits, estimatedUsageCredits, reserveUsageCredits, recommendedMaxCreditCap, targetMode, budgetMode, warnings, expectedCounters, reserveCounters, estimatedCounters, estimatedRates, and filterImpacts when available.
├`type`	`string`	Campaign type
├`creditReserved`	`number`	Credits to reserve on launch
├`targetEmails`	`integer`	Requested unique email lead goal
├`emailCollectionGoal`	`integer`nullable	Internal raw-email collection goal when validation may reduce deliverable emails
├`maxItemsToProcess`	`integer`nullable	Internal processing cap derived by the backend
├`maxProfilesToScan`	`integer`nullable	Internal profile scan cap derived by the backend
├`pricingVersion`	`string`	Pricing model used for the reservation estimate
├`reservationVersion`	`string`	Reservation schema version used by the backend
├`maxCreditCap`	`number`nullable	Configured hard stop cap for billable requests
├`estimatedCredits`	`number`nullable	Recommended/default hard cap from the reserve preview
├`estimatedUsageCredits`	`number`nullable	Expected usage credits before conservative cap buffer
├`reserveUsageCredits`	`number`nullable	Reserve-counter usage credits before conservative cap buffer
├`recommendedMaxCreditCap`	`number`nullable	Conservative recommended hard cap
├`summary`	`object`nullable	Customer-facing budget summary with max credit spend, scan count, hidden-email lookup estimate, and public email rate
├`targetMode`	`string`nullable	Whether the preview targets email leads
├`budgetMode`	`string`nullable	Whether the cap is recommended, user-limited, or custom
├`filterImpacts`	`array`nullable	Active filter impacts with selectivity and direct counter details
├`estimatedCounters`	`object`nullable	Estimated billable API-call counters from reserve preview
├`expectedCounters`	`object`nullable	Expected billable API-call counters from reserve preview
├`reserveCounters`	`object`nullable	Reserve billable API-call counters used for the hard cap estimate
├`estimatedRates`	`object`nullable	Per-counter credit rates used by reserve preview
├`rateRegistryChecksum`	`string`nullable	Checksum for the pricing rate registry used by the estimate
├`assumptions`	`object`nullable	Preview assumptions such as internal scan caps and rates
├`warnings`	`array`	Reserve-preview warnings shown before launch

POST/campaigns

Create campaign

Creates a new scraping campaign and reserves credits across Instagram, X/Twitter, YouTube, Facebook, LinkedIn, and TikTok. All supported campaign types should call /campaigns/reserve-preview first and send the same top-level targetEmails value to campaign creation. The backend derives internal scan caps. All reserve-preview campaign types may include maxCreditCap to hard-stop the worker before the next billable request. If maxCreditCap is omitted, the backend uses the reserved credit estimate as the cap. Deep email search is automatically enabled for supported non-email-only campaign types, and enableDeepEmailSearch: true remains accepted for backward compatibility. Email-only keyword campaigns should omit it. Enable enableEmailValidation to verify emails in real time during the campaign.

Request Bodyrequired

application/json

Field	Type	Description
`title`	`string`	Human-readable campaign name. Auto-generated if omitted.(max 100 chars)
`type`required	`string`	Campaign type — determines which inputs fields are required. `INSTAGRAM_HASHTAGINSTAGRAM_USER_FOLLOWERSINSTAGRAM_USER_FOLLOWINGINSTAGRAM_POST_LIKERSINSTAGRAM_POST_COMMENTERSINSTAGRAM_PROFILE_LISTINSTAGRAM_KEYWORD_SEARCHYOUTUBE_KEYWORD_SEARCHYOUTUBE_CHANNEL_SEARCHFACEBOOK_KEYWORD_SEARCHLINKEDIN_KEYWORD_SEARCHTWITTER_KEYWORD_SEARCHTIKTOK_KEYWORD_SEARCHTIKTOK_SEARCH_USERSTIKTOK_USER_FOLLOWERSTIKTOK_USER_FOLLOWINGTIKTOK_POST_COMMENTERSX_KEYWORD_SEARCHX_FOLLOWERSX_FOLLOWINGX_RETWEETSX_REPLIERS`
`inputs`required	`object`	Type-specific inputs. See endpoint description for which fields each campaign type requires.
├`hashtag`	`string`	Single hashtag for INSTAGRAM_HASHTAG campaigns. No # prefix needed.(max 100 chars)
├`hashtags`	`array`	Array of hashtags for INSTAGRAM_HASHTAG campaigns (max 20). Use instead of hashtag for multi-hashtag campaigns.(max 20 items)
├`targetUser`	`string`	Username for follower/following campaigns. No @ prefix needed.(max 100 chars)
├`mediaUrl`	`string<uri>`	Full post URL for liker/commenter/retweet/replier campaigns. Must be a valid HTTPS URL.(max 2048 chars)
├`keyword`	`string`	Single search keyword for keyword search campaigns.(max 200 chars)
├`keywords`	`array`	Array of search keywords (max 20). Use instead of keyword for multi-keyword campaigns.(max 20 items)
├`countries`	`array`	Optional list of 2-letter ISO 3166-1 alpha-2 country codes for keyword search, YouTube channel search, TikTok user search, Instagram targeting, and all X campaign types. Omit for global search. Max 10 countries.(max 10 items)
├`goal`	`string`	Optional legacy campaign goal for keyword-search campaigns. New campaign creation does not require this field. If sent, use one of: sell_products, find_influencers, remarketing, agency_leads, recruiting, other. `sell_productsfind_influencersremarketingagency_leadsrecruitingother`
├`goalOther`	`string`	Optional legacy free-text goal detail. Required only when a legacy client sends goal as "other".(max 200 chars)
`targetEmails`required	`integer`	Requested number of unique email leads. Send the same value used in /campaigns/reserve-preview.(1–1,000,000)
`maxCreditCap`	`number`	Optional hard stop for any reserve-preview campaign type, including Instagram. If omitted, the backend defaults the cap to the credits reserved at campaign creation.
`enableDeepEmailSearch`	`boolean`	Backward-compatible flag. Deep email search is automatically enabled for supported non-email-only campaign types; send true if included, and omit for email-only keyword campaigns.Default: `true for supported campaign types`
`enableEmailValidation`	`boolean`	Validate emails in real time during the campaign. Review the updated budget preview before launch.Default: `false`

Responses

201Campaign created

Field	Type	Description
`campaign`	`object`	The created campaign object
├`_id`	`string`	Campaign ID
├`createdBy`	`string`	User ID of creator
├`title`	`string`	Campaign name
├`type`	`string`	Campaign type
├`status`	`string`	Campaign status `pendingscrapingscraping_completedprocessing_emailsfully_completedfailedstopped`
├`inputs`	`object`	Campaign inputs
├`targetEmails`	`integer`	User-facing unique email lead goal
├`limits`	`object`	Backend-derived internal caps and legacy compatibility fields
├`enableDeepEmailSearch`	`boolean`	Whether automatic deep email search was applied for a supported campaign type
├`enableEmailValidation`	`boolean`	Whether email validation is enabled
├`emailScanCount`	`integer`	Emails found so far
├`profileScannedCount`	`integer`	Profiles scanned so far
├`progressPercentage`	`number`	Progress 0–100
├`creditSettlement`	`object`	Credit accounting
├`isSettled`	`boolean`	Whether credits have been settled
├`settledAt`	`string<date-time>`nullable	When settlement completed
├`creditReserved`	`number`	Credits reserved upfront
├`creditUsed`	`number`	Credits consumed
├`creditReturned`	`number`	Credits refunded
├`creditCharged`	`number`	Net credits charged
├`pricingVersion`	`string`	Pricing model used for the reservation estimate
├`reservationVersion`	`string`	Reservation schema version used by the backend
├`maxCreditCap`	`number`nullable	Configured hard stop cap for billable requests
├`estimatedCredits`	`number`nullable	Recommended/default hard cap from the reserve preview
├`estimatedUsageCredits`	`number`nullable	Expected usage credits before conservative cap buffer
├`reserveUsageCredits`	`number`nullable	Reserve-counter usage credits before conservative cap buffer
├`recommendedMaxCreditCap`	`number`nullable	Conservative recommended hard cap
├`summary`	`object`nullable	Customer-facing budget summary with max credit spend, scan count, hidden-email lookup estimate, and public email rate
├`targetMode`	`string`nullable	Whether the preview targets email leads
├`budgetMode`	`string`nullable	Whether the cap is recommended, user-limited, or custom
├`filterImpacts`	`array`nullable	Active filter impacts with selectivity and direct counter details
├`estimatedCounters`	`object`nullable	Estimated billable API-call counters from reserve preview
├`expectedCounters`	`object`nullable	Expected billable API-call counters from reserve preview
├`reserveCounters`	`object`nullable	Reserve billable API-call counters used for the hard cap estimate
├`estimatedRates`	`object`nullable	Per-counter credit rates used by reserve preview
├`rateRegistryChecksum`	`string`nullable	Checksum for the pricing rate registry used by the estimate
├`assumptions`	`object`nullable	Preview assumptions such as internal scan caps and rates
├`warnings`	`array`	Reserve-preview warnings shown before launch
├`breakdown`	`object`	Per-category credit usage (present once settled)
├`initialEmails`	`integer`	Profiles with an initial email
├`deepSearchEmails`	`integer`	Profiles with a hidden email found; audit counter for IG v2, not a direct fee
├`noEmails`	`integer`	Profiles scanned with no email
├`validations`	`integer`	Emails run through validation
├`settlementVersion`	`integer`	Internal settlement schema version
├`phaseState`	`object`	Authoritative per-phase state (scraping / deepsearch / validation / settlement)
├`scraping`	`object`	Scraping phase
├`status`	`string`	Phase status `not_applicablependingrunningcompletefailed`
├`startedAt`	`string<date-time>`nullable	When phase started
├`completedAt`	`string<date-time>`nullable	When phase completed
├`finalCounts`	`object`nullable	Sealed counts on completion
├`lastError`	`object`nullable	Most recent error (if any)
├`deepsearch`	`object`	Hidden-email search phase (same shape as scraping)
├`validation`	`object`	Email validation phase (same shape as scraping)
├`settlement`	`object`	Credit settlement lifecycle
├`status`	`string`	Settlement status `not_readyreadyin_progressdonefailed_retryingfailed_terminal`
├`attempts`	`integer`	Number of settlement attempts
├`lastAttemptAt`	`string<date-time>`nullable	Most recent settlement attempt
├`nextAttemptAt`	`string<date-time>`nullable	Next scheduled retry (if failed_retrying)
├`settledAt`	`string<date-time>`nullable	When settlement completed
├`lastError`	`object`nullable	Most recent settlement error
├`postValidation`	`object`nullable	Post-campaign validation status
├`createdAt`	`string<date-time>`	Creation timestamp
├`updatedAt`	`string<date-time>`	Last update timestamp
├`finishedAt`	`string<date-time>`nullable	Completion timestamp

Example

curl -X POST https://api.scravio.com/api/campaigns \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "INSTAGRAM_HASHTAG",
  "inputs": {
    "hashtags": [
      "fitness",
      "gym"
    ]
  },
  "targetEmails": 500,
  "enableDeepEmailSearch": true,
  "enableEmailValidation": true
}'

GET/campaigns

List campaigns

Returns a paginated list of the authenticated user's campaigns, sorted by creation date (newest first) by default. Soft-deleted campaigns are excluded automatically.

Parameters

Name	In	Type	Description
`page`	query	`integer`	Page numberDefault: `1`
`perPage`	query	`integer`	Items per page (max 100)Default: `10`
`status`	query	`string`	Filter by campaign status `pendingscrapingscraping_completedprocessing_emailsfully_completedfailedstopped`
`type`	query	`string`	Comma-separated campaign types or platform shorthands (e.g. INSTAGRAM, X)
`q`	query	`string`	Free-text search on title, hashtag, target user, media URL, keyword
`sortBy`	query	`string`	Sort fieldDefault: `createdAt` `createdAtprogressstatus`
`order`	query	`string`	Sort directionDefault: `desc` `ascdesc`
`from`	query	`string`	Start date filter (ISO 8601)
`to`	query	`string`	End date filter (ISO 8601)

Responses

200Paginated campaign list

Field	Type	Description
`items`	`array`	Array of Campaign objects
`pagination`	`object`	Pagination metadata
├`totalCount`	`integer`	Total items
├`totalPages`	`integer`	Total pages
├`currentPage`	`integer`	Current page
├`perPage`	`integer`	Items per page

Example

curl -X GET https://api.scravio.com/api/campaigns?page=1&perPage=10&status=fully_completed \
  -H "X-API-Key: sk_live_your_api_key"

GET/campaigns/{id}

Get campaign details

Returns full details of a single campaign owned by the authenticated user, including computed fields, target metadata, and credit settlement.

Parameters

Name	In	Type	Description
`id`required	path	`string`	Campaign ID

Responses

200Campaign details

Field	Type	Description
`_id`	`string`	Campaign ID
`title`	`string`	Campaign name
`type`	`string`	Campaign type
`status`	`string`	Campaign status `pendingscrapingscraping_completedprocessing_emailsfully_completedfailedstopped`
`inputs`	`object`	Campaign inputs
`targetEmails`	`integer`	User-facing unique email lead goal
`limits`	`object`	Backend-derived internal caps and legacy compatibility fields
`enableDeepEmailSearch`	`boolean`	Whether automatic deep email search was applied for a supported campaign type
`enableEmailValidation`	`boolean`	Whether email validation is enabled
`emailScanCount`	`integer`	Emails found
`profileScannedCount`	`integer`	Profiles scanned
`progressPercentage`	`number`	Progress 0–100
`maxItemsToProcess`	`integer`	Internal processing limit
`normalizedCounts`	`object`	Computed totals (only in detail response)
├`profiles`	`integer`	Total profiles
├`emails`	`integer`	Total emails
`creditSettlement`	`object`	Credit accounting
├`isSettled`	`boolean`	Whether credits have been settled
├`settledAt`	`string<date-time>`nullable	When settlement completed
├`creditReserved`	`number`	Credits reserved
├`creditUsed`	`number`	Credits consumed
├`creditReturned`	`number`	Credits refunded
├`creditCharged`	`number`	Net credits charged
├`pricingVersion`	`string`	Pricing model used for the reservation estimate
├`reservationVersion`	`string`	Reservation schema version used by the backend
├`maxCreditCap`	`number`nullable	Configured hard stop cap for billable requests
├`estimatedCredits`	`number`nullable	Recommended/default hard cap from the reserve preview
├`estimatedUsageCredits`	`number`nullable	Expected usage credits before conservative cap buffer
├`reserveUsageCredits`	`number`nullable	Reserve-counter usage credits before conservative cap buffer
├`recommendedMaxCreditCap`	`number`nullable	Conservative recommended hard cap
├`summary`	`object`nullable	Customer-facing budget summary with max credit spend, scan count, hidden-email lookup estimate, and public email rate
├`targetMode`	`string`nullable	Whether the preview targets email leads
├`budgetMode`	`string`nullable	Whether the cap is recommended, user-limited, or custom
├`filterImpacts`	`array`nullable	Active filter impacts with selectivity and direct counter details
├`estimatedCounters`	`object`nullable	Estimated billable API-call counters from reserve preview
├`expectedCounters`	`object`nullable	Expected billable API-call counters from reserve preview
├`reserveCounters`	`object`nullable	Reserve billable API-call counters used for the hard cap estimate
├`estimatedRates`	`object`nullable	Per-counter credit rates used by reserve preview
├`rateRegistryChecksum`	`string`nullable	Checksum for the pricing rate registry used by the estimate
├`assumptions`	`object`nullable	Preview assumptions such as internal scan caps and rates
├`warnings`	`array`	Reserve-preview warnings shown before launch
├`breakdown`	`object`	Per-category credit usage (present once settled)
├`initialEmails`	`integer`	Profiles with an initial email
├`deepSearchEmails`	`integer`	Profiles with a hidden email found; audit counter for IG v2, not a direct fee
├`noEmails`	`integer`	Profiles scanned with no email
├`validations`	`integer`	Emails run through validation
├`settlementVersion`	`integer`	Internal settlement schema version
`phaseState`	`object`	Authoritative per-phase state (scraping / deepsearch / validation / settlement). Updates push a `campaignUpdate` WebSocket event — treat as invalidation and refetch.
├`scraping`	`object`	Scraping phase
├`status`	`string`	Phase status `not_applicablependingrunningcompletefailed`
├`startedAt`	`string<date-time>`nullable	When phase started
├`completedAt`	`string<date-time>`nullable	When phase completed
├`finalCounts`	`object`nullable	Sealed counts on completion
├`lastError`	`object`nullable	Most recent error (if any)
├`deepsearch`	`object`	Hidden-email search phase (same shape as scraping)
├`validation`	`object`	Email validation phase (same shape as scraping)
├`settlement`	`object`	Credit settlement lifecycle
├`status`	`string`	Settlement status `not_readyreadyin_progressdonefailed_retryingfailed_terminal`
├`attempts`	`integer`	Number of settlement attempts
├`lastAttemptAt`	`string<date-time>`nullable	Most recent settlement attempt
├`nextAttemptAt`	`string<date-time>`nullable	Next scheduled retry (if failed_retrying)
├`settledAt`	`string<date-time>`nullable	When settlement completed
├`lastError`	`object`nullable	Most recent settlement error
`postValidation`	`object`nullable	Post-campaign validation status
├`status`	`string`	Validation status `idlevalidatingcompletedfailed`
├`total`	`integer`	Total emails to validate
├`validated`	`integer`	Emails validated so far
├`valid`	`integer`	Valid emails
├`invalid`	`integer`	Invalid emails
├`creditReserved`	`number`	Credits reserved for validation
├`creditUsed`	`number`	Credits used for validation
├`creditReturned`	`number`	Credits refunded after validation
├`startedAt`	`string<date-time>`	When validation started
├`completedAt`	`string<date-time>`	When validation completed
├`error`	`string`nullable	Error message if validation failed
`createdAt`	`string<date-time>`	Creation timestamp
`updatedAt`	`string<date-time>`	Last update
`finishedAt`	`string<date-time>`nullable	Completion timestamp
`platformUserId`	`string`	Platform-specific user ID of the target (profile-based campaigns)
`fullName`	`string`	Full name of the target user (profile-based campaigns)
`profilePicUrl`	`string`	Profile picture URL of the target user
`bio`	`string`	Biography of the target user
`followerCount`	`integer`	Follower count of the target user
`followingCount`	`integer`	Following count of the target user
`mediaCount`	`integer`	Media/post count of the target user
`isVerified`	`boolean`	Whether target user is verified on the platform
`isBusiness`	`boolean`	Whether target user has a business account
`hashtagMediaCount`	`integer`	Total media count for the hashtag (hashtag campaigns)
`targetPostAuthorUsername`	`string`	Username of the post author (post-based campaigns)
`targetPostAuthorName`	`string`	Display name of the post author
`targetPostAuthorProfilePicUrl`	`string`	Profile picture of the post author
`targetPostLikeCount`	`integer`	Like count on the target post
`targetPostCommentCount`	`integer`	Comment count on the target post
`targetPostId`	`string`	Platform-specific post ID
`targetPostCaptionText`	`string`	Caption text of the target post
`authorUsername`	`string`	Author username (X/Twitter campaigns)
`authorName`	`string`	Author display name (X/Twitter campaigns)
`commentCount`	`integer`	Comment count
`likeCount`	`integer`	Like count
`captionText`	`string`	Caption or post text
`targetFollowerCount`	`integer`	Target user follower count
`mediaPostCount`	`integer`	Target user media post count

404Campaign not found or does not belong to user

Example

curl -X GET https://api.scravio.com/api/campaigns/507f1f77bcf86cd799439011 \
  -H "X-API-Key: sk_live_your_api_key"

GET/campaigns/{id}/leads

List campaign leads

Returns the scraped leads (contacts) discovered by a campaign. Each lead represents a social-media profile and may include email, username, follower count, biography, and platform-specific metadata. Free accounts receive masked email values by default. Eligible free accounts can reveal up to five individual lead rows from the dashboard; exports remain masked until a confirmed purchase unlocks the account. Additional platform-specific fields (e.g. xPostText, linkedinHeadline, tiktokVideoUrl, facebookCategory) may be included when available.

Parameters

Name	In	Type	Description
`id`required	path	`string`	Campaign ID
`page`	query	`integer`	Page numberDefault: `1`
`perPage`	query	`integer`	Items per pageDefault: `10`
`hasEmail`	query	`boolean`	Filter leads with/without email
`validationStatus`	query	`string`	Filter by email validation result `validinvalidpending`
`platform`	query	`string`	Filter by source platform `instagramyoutubelinkedinfacebooktiktokx`
`sourceType`	query	`string`	Filter by lead source type
`emailSource`	query	`string`	Filter by how the email was discovered
`sortBy`	query	`string`	Sort fieldDefault: `hasEmail` `hasEmailfollowerCountscrapedAt`
`order`	query	`string`	Sort directionDefault: `desc` `ascdesc`

Responses

200Paginated lead list

Field	Type	Description
`items`	`array`	Array of Lead objects
├`_id`	`string`	Lead ID
├`campaignId`	`string`	Parent campaign ID
├`platform`	`string`	Source platform `instagramyoutubelinkedinfacebooktiktokx`
├`sourceType`	`string`	Lead source type `profilekeyword`
├`email`	`string<email>`nullable	Email address (may be masked)
├`emailMasked`	`boolean`	True when email fields are masked for the current account.
├`emailRevealed`	`boolean`	True when this lead has been individually revealed by the current free account.
├`canRevealEmail`	`boolean`	True when this lead can be revealed with the account free reveal quota.
├`emailSource`	`string`	How the email was discovered `initialdeep_searchnone`
├`phoneNumber`	`string`nullable	Phone number
├`username`	`string`nullable	Social media username
├`fullName`	`string`nullable	Display name
├`biography`	`string`nullable	Profile biography
├`followerCount`	`integer`nullable	Number of followers
├`followingCount`	`integer`nullable	Number following
├`mediaCount`	`integer`nullable	Number of posts/media
├`externalUrl`	`string`nullable	Website URL from profile
├`profilePicUrl`	`string`nullable	Profile picture URL
├`isPrivate`	`boolean`nullable	Whether account is private
├`isVerified`	`boolean`nullable	Whether account is verified
├`isBusiness`	`boolean`nullable	Whether account is a business
├`country`	`string`nullable	Country
├`accountCreatedDate`	`string<date-time>`nullable	When the account was created
├`latitude`	`number`nullable	Latitude coordinate
├`longitude`	`number`nullable	Longitude coordinate
├`cityName`	`string`nullable	City
├`addressStreet`	`string`nullable	Street address
├`emailValidation`	`object`nullable	Email validation result
├`status`	`string`	Validation status
├`isValid`	`boolean`	Whether email is valid
├`checkedAt`	`string<date-time>`	Validation timestamp
├`keyword`	`string`nullable	Keyword that matched this lead (keyword search campaigns)
├`scrapedAt`	`string<date-time>`	When the lead was scraped
`pagination`	`object`	Pagination metadata
├`totalCount`	`integer`	Total items
├`totalPages`	`integer`	Total pages
├`currentPage`	`integer`	Current page
├`perPage`	`integer`	Items per page

404Campaign not found or does not belong to user

Example

curl -X GET https://api.scravio.com/api/campaigns/507f1f77bcf86cd799439011/leads?hasEmail=true&page=1&perPage=20 \
  -H "X-API-Key: sk_live_your_api_key"

POST/campaigns/{id}/stop

Stop a running campaign

Sends a graceful stop signal to a running campaign. The campaign must be in an active state (pending, scraping, or processing_emails). The worker finishes the current batch, and unused reserved credits are automatically refunded. This endpoint is idempotent — calling it multiple times is safe. Rate limit: 5 requests per minute per campaign.

Parameters

Name	In	Type	Description
`id`required	path	`string`	Campaign ID

Responses

200Campaign stopped

Field	Type	Description
`campaignId`	`string`	Campaign ID
`stopRequested`	`boolean`	Whether stop was requested
`status`	`string`	Updated campaign status
`stoppedBy`	`string`	Who stopped the campaign
`stoppedReason`	`string`nullable	Reason for stopping

Example

curl -X POST https://api.scravio.com/api/campaigns/507f1f77bcf86cd799439011/stop \
  -H "X-API-Key: sk_live_your_api_key"

GET/campaigns/{id}/validate/preview

Preview validation cost

Returns a cost estimate for running post-campaign email validation. Call this before POST /campaigns/{id}/validate to check whether the account has enough credits.

Parameters

Name	In	Type	Description
`id`required	path	`string`	Campaign ID

Responses

200Validation cost preview

Field	Type	Description
`campaignId`	`string`	Campaign ID
`emailsToValidate`	`integer`	Number of emails to validate
`creditCost`	`number`	Total credits required
`currentBalance`	`number`	Account's current balance
`hasSufficientCredits`	`boolean`	Whether balance covers cost
`canValidate`	`boolean`	Whether validation can proceed

Example

curl -X GET https://api.scravio.com/api/campaigns/507f1f77bcf86cd799439011/validate/preview \
  -H "X-API-Key: sk_live_your_api_key"

POST/campaigns/{id}/validate

Start post-campaign email validation

Starts asynchronous email validation for all leads with emails in a completed campaign. Returns 202 Accepted; validation runs in the background. Prerequisites: campaign must be in fully_completed or stopped status. Account must have sufficient credits (check with GET /campaigns/{id}/validate/preview). Returns 409 if another validation is already running for this campaign. Credits are reserved upfront. After validation completes, unused credits are refunded. Subscribe to WebSocket events for real-time progress: - campaignValidationStarted — validation has begun - campaignValidationProgress — periodic update with validated, valid, invalid counts - campaignValidationCompleted — all emails validated with final credit breakdown - campaignValidationFailed — unrecoverable error occurred Rate limit: 3 requests per minute per campaign.

Parameters

Name	In	Type	Description
`id`required	path	`string`	Campaign ID

Responses

202Validation started

Field	Type	Description
`campaignId`	`string`	Campaign ID
`jobId`	`string`	Validation job ID
`emailsToValidate`	`integer`	Number of emails being validated
`creditCost`	`number`	Credits reserved
`status`	`string`	Validation status (validating)

Example

curl -X POST https://api.scravio.com/api/campaigns/507f1f77bcf86cd799439011/validate \
  -H "X-API-Key: sk_live_your_api_key"

Validation

Submit and manage standalone email validation jobs created from pasted email lists or uploaded CSV/TXT files. These jobs are separate from campaign validation, which is tracked on campaign objects.

GET/validation-jobs

List validation jobs

Returns a paginated list of standalone email validation jobs (created via POST /validation-jobs/text or the file upload endpoints). Post-campaign validations are tracked on the campaign object, not listed here.

Parameters

Name	In	Type	Description
`page`	query	`integer`	Page numberDefault: `1`
`limit`	query	`integer`	Items per pageDefault: `10`
`status`	query	`string`	Filter by job status `pendingparsingqueuedprocessingcompletedfailed`
`from`	query	`string`	Start date filter (ISO 8601)
`to`	query	`string`	End date filter (ISO 8601)
`sortBy`	query	`string`	Sort fieldDefault: `createdAt` `createdAtcompletedAt`
`order`	query	`string`	Sort directionDefault: `desc` `ascdesc`

Responses

200Paginated validation job list

Field	Type	Description
`success`	`boolean`	Request success status
`data`	`object`	Response data
├`jobs`	`array`	Array of ValidationJob objects
├`jobId`	`string`	Job ID
├`status`	`string`	Job status `pendingparsingqueuedprocessingcompletedfailed`
├`totalEmails`	`integer`	Total unique emails submitted
├`processedCount`	`integer`	Emails validated so far
├`validCount`	`integer`	Valid email count
├`invalidCount`	`integer`	Invalid email count
├`createdAt`	`string<date-time>`	Creation timestamp
├`completedAt`	`string<date-time>`nullable	Completion timestamp
├`downloadUrl`	`string`nullable	Results CSV download URL (when completed)
├`total`	`integer`	Total job count
├`page`	`integer`	Current page
├`pages`	`integer`	Total pages
`requestId`	`string`	Request tracking ID

Example

curl -X GET https://api.scravio.com/api/validation-jobs?page=1&limit=10 \
  -H "X-API-Key: sk_live_your_api_key"

POST/validation-jobs/text

Submit emails for validation

Creates a standalone email validation job from a list of email addresses. Independent of any campaign. Input: pass an emails array of strings, or a single comma-separated string. Duplicates are removed automatically (case-insensitive). Limits: minimum 1 email, maximum 5,000 after deduplication. Credits: reserved upfront. If cancelled before completion, unused credits are refunded. Concurrency: only one active job (pending or processing) per account. Wait for the current job to finish or cancel it before submitting a new one. Rate limit: 3 requests per hour.

Request Bodyrequired

application/json

Field	Type	Description
`emails`required	`array`	Array of email addresses, or a single comma-separated string. Duplicates removed automatically (case-insensitive). Max 5,000 after deduplication.

Responses

201Validation job created

Field	Type	Description
`success`	`boolean`	Request success status
`data`	`object`	Response data
├`jobId`	`string`	Job ID
├`status`	`string`	Job status
├`createdAt`	`string<date-time>`	Creation timestamp
├`creditsUsed`	`number`	Credits reserved
├`totalEmails`	`integer`	Unique emails after deduplication
`requestId`	`string`	Request tracking ID

Example

curl -X POST https://api.scravio.com/api/validation-jobs/text \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "emails": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]
}'

POST/validation-jobs/file

Request validation file upload

Creates a short-lived presigned upload URL for a CSV/TXT validation file. The file is uploaded directly to private object storage; the backend still verifies the object before parsing.

Request Bodyrequired

application/json

Field	Type	Description
`filename`required	`string`	Original filename for display and extension validation
`contentType`required	`string`	Browser-reported MIME type; backend treats this as advisory
`sizeBytes`required	`integer`	File size in bytes
`idempotencyKey`required	`string`	Client-generated key used to safely retry upload creation

Responses

201Upload ticket created

Field	Type	Description
`success`	`boolean`	Request success status
`data`	`object`	Upload ticket
├`uploadId`	`string`	Upload ID
├`key`	`string`	Private storage key generated by the backend
├`uploadUrl`	`string`	Short-lived presigned PUT URL
├`expiresAt`	`string<date-time>`	Upload URL expiry
├`maxSizeBytes`	`integer`	Maximum accepted file size
├`allowedContentTypes`	`array`	Accepted content types

Example

curl -X POST https://api.scravio.com/api/validation-jobs/file \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "filename": "leads.csv",
  "contentType": "text/csv",
  "sizeBytes": 123456,
  "idempotencyKey": "8b3d7c2e-5c7e-4a37-a0ea-b92fdb33bb5b"
}'

POST/validation-jobs/file/process

Parse uploaded validation file

Parses the private uploaded file and returns backend-confirmed review data. This step does not reserve credits or create the validation job.

Request Bodyrequired

application/json

Field	Type	Description
`uploadId`required	`string`	Upload ID returned by POST /validation-jobs/file
`key`required	`string`	Private storage key returned by POST /validation-jobs/file
`filename`required	`string`	Original filename for display and audit logs
`idempotencyKey`required	`string`	Same client-generated key used for the upload ticket

Responses

200File parsed

Field	Type	Description
`success`	`boolean`	Request success status
`data`	`object`	Backend-confirmed parse review
├`parseId`	`string`	Parse result ID used by the confirm endpoint
├`status`	`string`	Parse status
├`totalEmails`	`integer`	Unique emails detected
├`totalRows`	`integer`	Rows scanned
├`duplicatesRemoved`	`integer`	Duplicate emails removed
├`invalidRows`	`integer`	Rows ignored because no email was detected
├`estimatedCredits`	`number`	Estimated credits required to confirm the job
├`columns`	`array`	Detected candidate email columns
├`key`	`string`	Column key sent to confirm
├`label`	`string`	Column label shown to the user
├`emailLikeCount`	`integer`	Email-like values in this column
├`recommendedColumn`	`string`nullable	Backend-recommended column key

Example

curl -X PUT "https://storage.example/presigned-upload-url" \
  -H "Content-Type: text/csv" \
  --upload-file ./leads.csv

curl -X POST https://api.scravio.com/api/validation-jobs/file/process \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "uploadId": "upl_123",
  "key": "private/generated/key",
  "filename": "leads.csv",
  "idempotencyKey": "8b3d7c2e-5c7e-4a37-a0ea-b92fdb33bb5b"
}'

POST/validation-jobs/file/confirm

Confirm parsed validation file

Creates the validation job from backend-confirmed parse data and reserves credits. Retries must use the same idempotency key to avoid double-charging.

Request Bodyrequired

application/json

Field	Type	Description
`parseId`required	`string`	Parse ID returned by POST /validation-jobs/file/process
`selectedColumn`	`string`	Email column key selected by the user
`idempotencyKey`required	`string`	Same client-generated key used for upload and process

Responses

201Validation job queued

Field	Type	Description
`success`	`boolean`	Request success status
`data`	`object`	Queued validation job
├`jobId`	`string`	Validation job ID
├`status`	`string`	Initial job status
├`totalEmails`	`integer`	Unique emails queued for validation
├`creditsReserved`	`number`	Credits reserved for the job

Example

curl -X POST https://api.scravio.com/api/validation-jobs/file/confirm \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "parseId": "parse_123",
  "selectedColumn": "email",
  "idempotencyKey": "8b3d7c2e-5c7e-4a37-a0ea-b92fdb33bb5b"
}'

GET/validation-jobs/{id}

Get validation job details

Returns full details of a validation job including real-time progress. The downloadUrl field is only present when the job status is completed.

Parameters

Name	In	Type	Description
`id`required	path	`string`	Validation job ID

Responses

200Validation job details

Field	Type	Description
`success`	`boolean`	Request success status
`data`	`object`	ValidationJob object
├`jobId`	`string`	Job ID
├`status`	`string`	Job status `pendingparsingqueuedprocessingcompletedfailed`
├`statusReason`	`string`nullable	Human-readable reason if cancelled or failed
├`totalEmails`	`integer`	Total unique emails submitted
├`processedCount`	`integer`	Emails validated so far
├`validCount`	`integer`	Valid email count
├`invalidCount`	`integer`	Invalid email count
├`externalRequestId`	`string`nullable	External tracking ID
├`createdAt`	`string<date-time>`	Creation timestamp
├`updatedAt`	`string<date-time>`	Last update timestamp
├`completedAt`	`string<date-time>`nullable	Completion timestamp
├`downloadUrl`	`string`nullable	Pre-signed URL to download results CSV (only when completed)
`requestId`	`string`	Request tracking ID

404Job not found or does not belong to user

Example

curl -X GET https://api.scravio.com/api/validation-jobs/507f1f77bcf86cd799439013 \
  -H "X-API-Key: sk_live_your_api_key"

GET/validation-jobs/{id}/download

Get validation results download URL

Returns a short-lived pre-signed URL for downloading completed validation results as CSV. The URL is only available after the job status is completed.

Parameters

Name	In	Type	Description
`id`required	path	`string`	Validation job ID

Responses

200Validation results download URL

Field	Type	Description
`success`	`boolean`	Request success status
`data`	`object`	Download URL response
├`downloadUrl`	`string`	Short-lived pre-signed CSV download URL
├`expiresIn`	`integer`nullable	Seconds until the URL expires
`requestId`	`string`	Request tracking ID

404Job not found, incomplete, or does not belong to user

Example

curl -X GET https://api.scravio.com/api/validation-jobs/507f1f77bcf86cd799439013/download \
  -H "X-API-Key: sk_live_your_api_key"

Exports

Create and download CSV/XLSX list exports from campaign leads.

POST/list-exports

Create a list export

Creates a CSV or XLSX export file containing leads from a campaign. Processing runs asynchronously — returns 201 and you can poll GET /list-exports/{id}/download for the result. Idempotent: if a pending/processing export already exists for the same campaign and options, the existing export is returned. Rate limit: 5 requests per hour.

Request Bodyrequired

application/json

Field	Type	Description
`campaignId`required	`string`	Campaign ID to export leads from
`emailOnly`	`boolean`	Export only leads that have an emailDefault: `false`
`onlyValidEmails`	`boolean`	Export only leads with validated (deliverable) emailsDefault: `false`
`fileFormat`	`string`	Export file formatDefault: `csv` `csvxlsx`

Responses

201Export created or processing

Field	Type	Description
`success`	`boolean`	Request success status
`data`	`object`	Export data
├`exportId`	`string`	Export ID
├`status`	`string`	Export status
├`progress`	`number`	Progress percentage
├`isEmailOnly`	`boolean`	Whether export is email-only
├`onlyValidEmails`	`boolean`	Whether export is valid-only
├`fileFormat`	`string`	File format (csv or xlsx) `csvxlsx`
├`createdAt`	`string<date-time>`	Creation timestamp
├`completedAt`	`string<date-time>`nullable	Completion timestamp
`requestId`	`string`	Request tracking ID

200Existing completed export reused (same campaign and options, data unchanged)

Example

curl -X POST https://api.scravio.com/api/list-exports \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "campaignId": "507f1f77bcf86cd799439011",
  "emailOnly": true,
  "fileFormat": "csv"
}'

GET/list-exports

List exports

Returns a paginated list of the account's export jobs. Filter by campaignId or status.

Parameters

Name	In	Type	Description
`page`	query	`integer`	Page numberDefault: `1`
`perPage`	query	`integer`	Items per pageDefault: `10`
`campaignId`	query	`string`	Filter by campaign ID
`status`	query	`string`	Filter by export status `pendingprocessingcompletedfailed`
`sortBy`	query	`string`	Sort fieldDefault: `createdAt` `createdAtcompletedAtstatus`
`order`	query	`string`	Sort directionDefault: `desc` `ascdesc`

Responses

200Paginated export list

Field	Type	Description
`success`	`boolean`	Request success status
`data`	`object`	Response data
├`exports`	`array`	Array of ListExport objects
├`exportId`	`string`	Export ID
├`campaignId`	`string`	Campaign ID
├`status`	`string`	Export status `pendingprocessingcompletedfailed`
├`progress`	`number`	Progress percentage
├`isEmailOnly`	`boolean`	Whether email-only
├`onlyValidEmails`	`boolean`	Whether valid-only
├`filename`	`string`nullable	Output filename (after completion)
├`totalRecords`	`integer`	Total records exported (after completion)
├`fileSize`	`integer`nullable	File size in bytes (after completion)
├`fileFormat`	`string`	File format `csvxlsx`
├`createdAt`	`string<date-time>`	Creation timestamp
├`completedAt`	`string<date-time>`nullable	Completion timestamp
├`pagination`	`object`	Pagination metadata
├`totalCount`	`integer`	Total items
├`totalPages`	`integer`	Total pages
├`currentPage`	`integer`	Current page
├`perPage`	`integer`	Items per page
`requestId`	`string`	Request tracking ID

Example

curl -X GET https://api.scravio.com/api/list-exports?page=1&perPage=10 \
  -H "X-API-Key: sk_live_your_api_key"

GET/list-exports/{id}/download

Get export download URL

Returns a download URL and filename for a completed export file. The export must have status: completed — requesting a download for a pending/processing/failed export returns 400.

Parameters

Name	In	Type	Description
`id`required	path	`string`	Export ID

Responses

200Download URL

Field	Type	Description
`success`	`boolean`	Request success status
`data`	`object`	Download data
├`downloadUrl`	`string<uri>`	Pre-signed download URL
├`filename`	`string`	Suggested filename
`requestId`	`string`	Request tracking ID

Example

curl -X GET https://api.scravio.com/api/list-exports/507f1f77bcf86cd799439014/download \
  -H "X-API-Key: sk_live_your_api_key"

Credits

View your credit transaction history and balance changes.

GET/credit-transactions

List credit transactions

Returns a paginated ledger of all credit transactions. Each entry records a single balance change with balanceBefore, amount (negative for deductions, positive for credits), and balanceAfter.

Parameters

Name	In	Type	Description
`page`	query	`integer`	Page numberDefault: `1`
`perPage`	query	`integer`	Items per pageDefault: `10`
`type`	query	`string`	Comma-separated transaction types `CAMPAIGN_RESERVATIONCAMPAIGN_SETTLEMENTCAMPAIGN_OVERAGEEMAIL_VALIDATION_DEDUCTIONEMAIL_VALIDATION_REFUNDSUBSCRIPTION_INITIALSUBSCRIPTION_RENEWALSUBSCRIPTION_UPGRADESUBSCRIPTION_DOWNGRADEPAYMENT_PADDLEPAYMENT_CRYPTOMUSPAYMENT_STRIPE_TOPUPPAYMENT_PADDLE_TOPUPADMIN_CREDIT_ADJUSTMENT`
`campaignId`	query	`string`	Filter by campaign ID
`from`	query	`string`	Start date filter (ISO 8601)
`to`	query	`string`	End date filter (ISO 8601)
`sortBy`	query	`string`	Sort fieldDefault: `timestamp` `timestampamount`
`order`	query	`string`	Sort directionDefault: `desc` `ascdesc`

Responses

200Paginated transaction list

Field	Type	Description
`transactions`	`array`	Array of CreditTransaction objects
├`id`	`string`	Transaction ID
├`timestamp`	`string<date-time>`	Transaction timestamp
├`balanceBefore`	`number`	Balance before transaction
├`amount`	`number`	Amount (negative = deduction, positive = credit)
├`balanceAfter`	`number`	Balance after transaction
├`type`	`string`	Transaction type
├`description`	`string`	Human-readable description
├`campaignId`	`string`nullable	Related campaign ID
├`paymentId`	`string`nullable	Payment transaction ID (payment transactions only)
├`paymentGateway`	`string`nullable	Payment gateway name (payment transactions only)
├`correlationId`	`string`nullable	Correlation ID for tracking related transactions
├`metadata`	`object`nullable	Additional metadata
├`createdAt`	`string<date-time>`	Creation timestamp
`pagination`	`object`	Pagination metadata
├`totalCount`	`integer`	Total items
├`totalPages`	`integer`	Total pages
├`currentPage`	`integer`	Current page
├`perPage`	`integer`	Items per page
`requestId`	`string`	Request tracking ID

Example

curl -X GET https://api.scravio.com/api/credit-transactions?page=1&perPage=10&sortBy=timestamp&order=desc \
  -H "X-API-Key: sk_live_your_api_key"

Table of Contents