US EN
Login

API

API Methods
To open access to our API, contact our support service via Telegram at the link: @spy.house_support

Retrieving a list of languages

Request link

Parameter Data type Required Description
api_key String Yes Unique API key for request authentication.
Parameter Data type Description
status String Field indicating successful request execution ("success") or error ("error").
msg String Error message or additional request information.
code Number Response code, e.g., 200 for a successful request.
data Array Array of available languages.
└ lang_id Number Unique language identifier.
└ name String Language name in English.
└ iso_code String ISO language code (e.g., "EN" for English, "RU" for Russian).
<?php


    function api_request($data = [])
    {
        $ch = curl_init('https://spy.house/api/filters/languages');

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
        curl_setopt($ch, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V4);
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

        $body = curl_exec($ch);
        $info = curl_getinfo($ch);

        curl_close($ch);

        if ( ! empty($info['http_code']) && $info['http_code'] == 200) {
            return json_decode($body, TRUE);
        }
    }


    $body_request = ['api_key' => 'YOUR_API_KEY'];


    $api_request = api_request($body_request);
    if ( ! empty($api_request['status'])) {
        echo '<pre>';
        print_r($api_request);
        echo '</pre>';
    }

Retrieving a list of countries

Request link

Parameter Data type Required Description
api_key String Yes Unique API key for request authentication.
Parameter Data type Description
status String Field indicating successful request execution ("success") or error ("error").
msg String Error message or additional request information.
code Number Response code, e.g., 200 for a successful request.
data Array Array of available countries.
└ country_id Number Unique country identifier.
└ name String Country name in English.
└ iso_code String ISO 3166-1 alpha-2 country code (e.g., "US" for United States).
└ iso_code_3 String ISO 3166-1 alpha-3 country code (e.g., "USA" for United States).
<?php


    function api_request($data = [])
    {
        $ch = curl_init('https://spy.house/api/filters/countries');

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
        curl_setopt($ch, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V4);
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

        $body = curl_exec($ch);
        $info = curl_getinfo($ch);

        curl_close($ch);

        if ( ! empty($info['http_code']) && $info['http_code'] == 200) {
            return json_decode($body, TRUE);
        }
    }


    $body_request = ['api_key' => 'YOUR_API_KEY'];


    $api_request = api_request($body_request);
    if ( ! empty($api_request['status'])) {
        echo '<pre>';
        print_r($api_request);
        echo '</pre>';
    }

Retrieving a list of browsers

Request link

Parameter Data type Required Description
api_key String Yes Unique API key for request authentication.
Parameter Data type Description
status String Field indicating successful request execution ("success") or error ("error").
msg String Error message or additional request information.
code Number Response code, e.g., 200 for a successful request.
data Array Array of available browsers.
└ browser_id Number Unique browser identifier.
└ name String Browser name.
<?php


    function api_request($data = [])
    {
        $ch = curl_init('https://spy.house/api/filters/browsers');

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
        curl_setopt($ch, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V4);
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

        $body = curl_exec($ch);
        $info = curl_getinfo($ch);

        curl_close($ch);

        if ( ! empty($info['http_code']) && $info['http_code'] == 200) {
            return json_decode($body, TRUE);
        }
    }


    $body_request = ['api_key' => 'YOUR_API_KEY'];


    $api_request = api_request($body_request);
    if ( ! empty($api_request['status'])) {
        echo '<pre>';
        print_r($api_request);
        echo '</pre>';
    }

Retrieving a list of devices

Request link

Parameter Data type Required Description
api_key String Yes Unique API key for request authentication.
Parameter Data type Description
status String Field indicating successful request execution ("success") or error ("error").
msg String Error message or additional request information.
code Number Response code, e.g., 200 for a successful request.
data Array Array of available device types.
└ device_id Number Unique device type identifier.
└ name String Device type display name.
└ value String Device type value for API requests.
<?php


    function api_request($data = [])
    {
        $ch = curl_init('https://spy.house/api/filters/devices');

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
        curl_setopt($ch, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V4);
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

        $body = curl_exec($ch);
        $info = curl_getinfo($ch);

        curl_close($ch);

        if ( ! empty($info['http_code']) && $info['http_code'] == 200) {
            return json_decode($body, TRUE);
        }
    }


    $body_request = ['api_key' => 'YOUR_API_KEY'];


    $api_request = api_request($body_request);
    if ( ! empty($api_request['status'])) {
        echo '<pre>';
        print_r($api_request);
        echo '</pre>';
    }

Retrieving a list of operating systems

Request link

Parameter Data type Required Description
api_key String Yes Unique API key for request authentication.
Parameter Data type Description
status String Field indicating successful request execution ("success") or error ("error").
msg String Error message or additional request information.
code Number Response code, e.g., 200 for a successful request.
data Array Array of available operating systems.
└ os_id Number Unique operating system identifier.
└ name String Operating system display name.
└ value String Operating system value for API requests.
<?php


    function api_request($data = [])
    {
        $ch = curl_init('https://spy.house/api/filters/operating_systems');

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
        curl_setopt($ch, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V4);
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

        $body = curl_exec($ch);
        $info = curl_getinfo($ch);

        curl_close($ch);

        if ( ! empty($info['http_code']) && $info['http_code'] == 200) {
            return json_decode($body, TRUE);
        }
    }


    $body_request = ['api_key' => 'YOUR_API_KEY'];


    $api_request = api_request($body_request);
    if ( ! empty($api_request['status'])) {
        echo '<pre>';
        print_r($api_request);
        echo '</pre>';
    }

Retrieving a list of advertising networks

Request link

Parameter Data type Required Description
api_key String Yes Unique API key for request authentication.
Parameter Data type Description
status String Field indicating successful request execution ("success") or error ("error").
msg String Error message or additional request information.
code Number Response code, e.g., 200 for a successful request.
data Array Array of available advertising networks.
└ network_id Number Unique advertising network identifier.
└ name String Advertising network display name.
└ value String Advertising network value for API requests.
└ logo String URL to the advertising network logo.
<?php


    function api_request($data = [])
    {
        $ch = curl_init('https://spy.house/api/filters/advertising_networks');

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
        curl_setopt($ch, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V4);
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

        $body = curl_exec($ch);
        $info = curl_getinfo($ch);

        curl_close($ch);

        if ( ! empty($info['http_code']) && $info['http_code'] == 200) {
            return json_decode($body, TRUE);
        }
    }


    $body_request = ['api_key' => 'YOUR_API_KEY'];


    $api_request = api_request($body_request);
    if ( ! empty($api_request['status'])) {
        echo '<pre>';
        print_r($api_request);
        echo '</pre>';
    }

Search Push Creatives

Search for push notification creatives with various filters. Returns paginated results.

Request link

Parameter Data type Required Description
api_key String Yes Unique API key for request authentication.
limit Number No Number of items per page (10-100). Default: 10.
offset Number No Number of items to skip. Used for pagination. Default: 0.
keyword String No Search keyword to filter creatives by title or description.
countries Array No Array of country ISO-2 codes (e.g., ["US", "GB", "DE"]).
country_ids Array No Array of country IDs from /api/filters/countries endpoint. Takes precedence over countries.
languages Array No Array of language ISO codes (e.g., ["EN", "RU", "DE"]).
lang_ids Array No Array of language IDs from /api/filters/languages endpoint. Takes precedence over languages.
advertising_networks Array No Array of advertising network names.
network_ids Array No Array of network IDs from /api/filters/advertising-networks endpoint. Takes precedence over advertising_networks.
browsers Array No Array of browser names.
browser_ids Array No Array of browser IDs from /api/filters/browsers endpoint. Takes precedence over browsers.
operating_systems Array No Array of operating system values (e.g., ["windows", "macos", "android"]).
devices Array No Array of device types (e.g., ["desktop", "mobile", "tablet"]).
date_from String No Start date for filtering (format: Y-m-d, e.g., "2025-01-01").
date_to String No End date for filtering (format: Y-m-d, e.g., "2025-12-31").
sort_by String No Sort field: creation, activity, popularity.
sort_order String No Sort direction: asc or desc.
only_adult Boolean No Filter adult content only. Boolean (true/false).
Parameter Data type Description
status String Field indicating successful request execution ("success") or error ("error").
msg String Error message or additional request information.
code Number Response code, e.g., 200 for a successful request.
data Object Array of flow data matching the request.
└ format String Creative format (push, inpage, facebook, tiktok).
└ items Array Array of creative objects.
  └ id Number Unique creative identifier.
  └ title String Creative title text.
  └ description String Creative description text.
  └ category String Creative format/category (push, inpage, facebook, tiktok).
  └ country Object Country information object (code, name, iso_code_3).
    └ code String ISO 3166-1 alpha-2 country code (e.g., "US" for United States).
    └ name String Country name in English.
    └ iso_code_3 String ISO 3166-1 alpha-3 country code (e.g., "USA" for United States).
  └ file_size String Formatted total file size.
  └ icon_url String URL to the creative icon image.
  └ landing_url String Landing page URL.
  └ created_at String Creative creation date (Y-m-d format).
  └ advertising_networks Array Array of advertising network names.
  └ languages Array Array of language ISO codes.
  └ operating_systems Array Array of operating system values.
  └ browsers Array Array of browser names.
  └ devices Array Array of device types.
  └ main_image_url String URL to the main creative image.
  └ is_adult Boolean Whether the creative contains adult content.
  └ is_active Boolean Whether the creative is currently active.
└ pagination Object Pagination information object.
  └ total Number Total number of creatives matching the filters.
  └ limit Number Number of items per page.
  └ offset Number Current offset.
  └ has_more Boolean Whether more items are available.
  └ returned_count Number Number of items returned in this response.
└ filters_applied Object Object containing the filters that were applied.
└ timestamp String Response timestamp in ISO 8601 format.
<?php

function searchPushCreatives($params = [])
{
    $ch = curl_init('https://spy.house/api/search/push');

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V4);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));

    $body = curl_exec($ch);
    $info = curl_getinfo($ch);

    curl_close($ch);

    if (!empty($info['http_code']) && $info['http_code'] == 200) {
        return json_decode($body, TRUE);
    }
    return null;
}

// Example 1: Basic search with API key
$params = [
    'api_key' => 'YOUR_API_KEY',
    'limit' => 20,
    'offset' => 0,
];

$result = searchPushCreatives($params);

if ($result && $result['status'] === 'success') {
    foreach ($result['data']['items'] as $creative) {
        echo "ID: " . $creative['id'] . " - " . $creative['title'] . "\n";
    }
    echo "Total: " . $result['data']['pagination']['total'] . "\n";
}

// Example 2: Search with ISO codes/names filters
$paramsWithFilters = [
    'api_key' => 'YOUR_API_KEY',
    'limit' => 50,
    'offset' => 0,
    'keyword' => 'casino',
    'countries' => ['US', 'GB', 'DE'],  // ISO-2 codes
    'languages' => ['EN'],                 // ISO codes
    'browsers' => ['Chrome', 'Firefox'],    // Browser names
    'sort_by' => 'creation',
    'sort_order' => 'desc',
];

$filteredResult = searchPushCreatives($paramsWithFilters);

// Example 3: Search with ID-based filters (recommended)
// Use IDs from /api/filters/* endpoints for better performance
$paramsWithIds = [
    'api_key' => 'YOUR_API_KEY',
    'limit' => 50,
    'offset' => 0,
    'keyword' => 'casino',
    'country_ids' => [1, 2, 3],              // IDs from /api/filters/countries
    'lang_ids' => [1],                      // IDs from /api/filters/languages
    'network_ids' => [5, 10],              // IDs from /api/filters/advertising-networks
    'browser_ids' => [1, 2],               // IDs from /api/filters/browsers
    'sort_by' => 'creation',
    'sort_order' => 'desc',
];

$resultWithIds = searchPushCreatives($paramsWithIds);

// Note: ID-based filters take precedence over name-based filters
// If both country_ids and countries are provided, country_ids will be used

Search Inpage Creatives

Search for inpage (in-page push) creatives with various filters.

Request link

Parameter Data type Required Description
api_key String Yes Unique API key for request authentication.
limit Number No Number of items per page (10-100). Default: 10.
offset Number No Number of items to skip. Used for pagination. Default: 0.
keyword String No Search keyword to filter creatives by title or description.
countries Array No Array of country ISO-2 codes (e.g., ["US", "GB", "DE"]).
country_ids Array No Array of country IDs from /api/filters/countries endpoint. Takes precedence over countries.
languages Array No Array of language ISO codes (e.g., ["EN", "RU", "DE"]).
lang_ids Array No Array of language IDs from /api/filters/languages endpoint. Takes precedence over languages.
advertising_networks Array No Array of advertising network names.
network_ids Array No Array of network IDs from /api/filters/advertising-networks endpoint. Takes precedence over advertising_networks.
browsers Array No Array of browser names.
browser_ids Array No Array of browser IDs from /api/filters/browsers endpoint. Takes precedence over browsers.
operating_systems Array No Array of operating system values (e.g., ["windows", "macos", "android"]).
devices Array No Array of device types (e.g., ["desktop", "mobile", "tablet"]).
date_from String No Start date for filtering (format: Y-m-d, e.g., "2025-01-01").
date_to String No End date for filtering (format: Y-m-d, e.g., "2025-12-31").
sort_by String No Sort field: creation, activity, popularity.
sort_order String No Sort direction: asc or desc.
only_adult Boolean No Filter adult content only. Boolean (true/false).
Parameter Data type Description
status String Field indicating successful request execution ("success") or error ("error").
msg String Error message or additional request information.
code Number Response code, e.g., 200 for a successful request.
data Object Array of flow data matching the request.
└ format String Creative format (push, inpage, facebook, tiktok).
└ items Array Array of creative objects.
  └ id Number Unique creative identifier.
  └ title String Creative title text.
  └ description String Creative description text.
  └ category String Creative format/category (push, inpage, facebook, tiktok).
  └ country Object Country information object (code, name, iso_code_3).
    └ code String ISO 3166-1 alpha-2 country code (e.g., "US" for United States).
    └ name String Country name in English.
    └ iso_code_3 String ISO 3166-1 alpha-3 country code (e.g., "USA" for United States).
  └ file_size String Formatted total file size.
  └ icon_url String URL to the creative icon image.
  └ landing_url String Landing page URL.
  └ created_at String Creative creation date (Y-m-d format).
  └ advertising_networks Array Array of advertising network names.
  └ languages Array Array of language ISO codes.
  └ operating_systems Array Array of operating system values.
  └ browsers Array Array of browser names.
  └ devices Array Array of device types.
  └ main_image_url String URL to the main creative image.
  └ is_adult Boolean Whether the creative contains adult content.
  └ is_active Boolean Whether the creative is currently active.
└ pagination Object Pagination information object.
  └ total Number Total number of creatives matching the filters.
  └ limit Number Number of items per page.
  └ offset Number Current offset.
  └ has_more Boolean Whether more items are available.
  └ returned_count Number Number of items returned in this response.
└ filters_applied Object Object containing the filters that were applied.
└ timestamp String Response timestamp in ISO 8601 format.
<?php

function searchInpageCreatives($params = [])
{
    $ch = curl_init('https://spy.house/api/search/inpage');

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V4);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));

    $body = curl_exec($ch);
    $info = curl_getinfo($ch);

    curl_close($ch);

    if (!empty($info['http_code']) && $info['http_code'] == 200) {
        return json_decode($body, TRUE);
    }
    return null;
}

// Example 1: Basic search with API key
$params = [
    'api_key' => 'YOUR_API_KEY',
    'limit' => 20,
    'offset' => 0,
];

$result = searchInpageCreatives($params);

if ($result && $result['status'] === 'success') {
    foreach ($result['data']['items'] as $creative) {
        echo "ID: " . $creative['id'] . " - " . $creative['title'] . "\n";
    }
    echo "Total: " . $result['data']['pagination']['total'] . "\n";
}

// Example 2: Search with ISO codes/names filters
$paramsWithFilters = [
    'api_key' => 'YOUR_API_KEY',
    'limit' => 50,
    'offset' => 0,
    'keyword' => 'casino',
    'countries' => ['US', 'GB', 'DE'],  // ISO-2 codes
    'languages' => ['EN'],                 // ISO codes
    'browsers' => ['Chrome', 'Firefox'],    // Browser names
    'sort_by' => 'creation',
    'sort_order' => 'desc',
];

$filteredResult = searchInpageCreatives($paramsWithFilters);

// Example 3: Search with ID-based filters (recommended)
// Use IDs from /api/filters/* endpoints for better performance
$paramsWithIds = [
    'api_key' => 'YOUR_API_KEY',
    'limit' => 50,
    'offset' => 0,
    'keyword' => 'casino',
    'country_ids' => [1, 2, 3],              // IDs from /api/filters/countries
    'lang_ids' => [1],                      // IDs from /api/filters/languages
    'network_ids' => [5, 10],              // IDs from /api/filters/advertising-networks
    'browser_ids' => [1, 2],               // IDs from /api/filters/browsers
    'sort_by' => 'creation',
    'sort_order' => 'desc',
];

$resultWithIds = searchInpageCreatives($paramsWithIds);

// Note: ID-based filters take precedence over name-based filters
// If both country_ids and countries are provided, country_ids will be used

Search Facebook Creatives

Search for Facebook ads creatives with various filters. When results are low, the API can start Live Search and return a scrapingJob for polling.

If scrapingJob.needStartPolling is true, call the same endpoint with isPolling=true and job_id to receive new items. If status is recently_completed or rejected, no job is created and polling should not be started.

Live Search starts only when exactly one country is specified in the countries array.

Live Search starts only when a non-empty keyword is provided.

Request link

Parameter Data type Required Description
api_key String Yes Unique API key for request authentication.
limit Number No Number of items per page (10-100). Default: 10.
offset Number No Number of items to skip. Used for pagination. Default: 0.
keyword String No Search keyword to filter creatives by title or description.
countries Array No Array of country ISO-2 codes (e.g., ["US", "GB", "DE"]).
country_ids Array No Array of country IDs from /api/filters/countries endpoint. Takes precedence over countries.
languages Array No Array of language ISO codes (e.g., ["EN", "RU", "DE"]).
lang_ids Array No Array of language IDs from /api/filters/languages endpoint. Takes precedence over languages.
date_from String No Start date for filtering (format: Y-m-d, e.g., "2025-01-01").
date_to String No End date for filtering (format: Y-m-d, e.g., "2025-12-31").
sort_by String No Sort field: creation, activity, popularity.
sort_order String No Sort direction: asc or desc.
status String No Ad status filter: ALL, ACTIVE, INACTIVE.
media_type String No Media type filter: ALL, IMAGE, VIDEO.
search_type String No Search type: keyword_unordered, keyword_exact_phrase.
isPolling Boolean No Enable polling for live search updates. Use with job_id.
lastId Number No Last creative ID received for incremental polling (optional).
perPage Number No Expected page size for low-results detection (12-96).
job_id String No Live search job id from scrapingJob. Required when isPolling=true.
Parameter Data type Description
status String Field indicating successful request execution ("success") or error ("error").
msg String Error message or additional request information.
code Number Response code, e.g., 200 for a successful request.
data Object Array of flow data matching the request.
└ format String Creative format (push, inpage, facebook, tiktok).
└ items Array Array of creative objects.
  └ id Number Unique creative identifier.
  └ title String Creative title text.
  └ description String Creative description text.
  └ category String Creative format/category (push, inpage, facebook, tiktok).
  └ country Object Country information object (code, name, iso_code_3).
    └ code String ISO 3166-1 alpha-2 country code (e.g., "US" for United States).
    └ name String Country name in English.
    └ iso_code_3 String ISO 3166-1 alpha-3 country code (e.g., "USA" for United States).
  └ file_size String Formatted total file size.
  └ icon_url String URL to the creative icon image.
  └ landing_url String Landing page URL.
  └ created_at String Creative creation date (Y-m-d format).
  └ advertising_networks Array Array of advertising network names.
  └ languages Array Array of language ISO codes.
  └ operating_systems Array Array of operating system values.
  └ browsers Array Array of browser names.
  └ devices Array Array of device types.
  └ main_image_url String URL to the main creative image.
  └ has_video Boolean Whether the creative contains video.
  └ video_url String URL to the video (if has_video is true).
  └ video_duration Number Video duration in seconds (if applicable).
  └ social_likes Number Number of social likes (for social ads).
  └ social_comments Number Number of social comments (for social ads).
  └ social_shares Number Number of social shares (for social ads).
  └ is_adult Boolean Whether the creative contains adult content.
  └ is_active Boolean Whether the creative is currently active.
└ pagination Object Pagination information object.
  └ total Number Total number of creatives matching the filters.
  └ limit Number Number of items per page.
  └ offset Number Current offset.
  └ has_more Boolean Whether more items are available.
  └ returned_count Number Number of items returned in this response.
└ filters_applied Object Object containing the filters that were applied.
└ scrapingJob Object Live search job object (present when live search is started or active).
  └ type String Live search type identifier (e.g., facebook_search).
  └ status String Job status: dispatched, running, post_processing, completed, failed, error, recently_completed, rejected.
  └ needStartPolling Boolean Whether the client should start polling for updates.
  └ needStopPolling Boolean Whether the client should stop polling.
  └ job_id String Job identifier for polling (absent when status is recently_completed or rejected).
  └ polling_interval_seconds Number Recommended polling interval in seconds.
  └ estimatedDuration Number Estimated duration in seconds (0 when completed or recently_completed).
  └ message String Additional status message from the server or parser.
  └ retry_after_seconds Number How long to wait before retrying when recently_completed/rejected (if provided).
  └ error String Error details (present when status is failed or error).
└ timestamp String Response timestamp in ISO 8601 format.
<?php

function searchFacebookCreatives($params = [])
{
    $ch = curl_init('https://spy.house/api/search/facebook');

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V4);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));

    $body = curl_exec($ch);
    $info = curl_getinfo($ch);

    curl_close($ch);

    if (!empty($info['http_code']) && $info['http_code'] == 200) {
        return json_decode($body, TRUE);
    }
    return null;
}

// Example 1: Basic search with API key
$params = [
    'api_key' => 'YOUR_API_KEY',
    'limit' => 20,
    'offset' => 0,
    'keyword' => 'casino',
    'countries' => ['US'],
];

// Example 2: Social filters (status/media_type/search_type)
$paramsWithSocialFilters = [
    'api_key' => 'YOUR_API_KEY',
    'limit' => 20,
    'offset' => 0,
    'keyword' => 'casino',
    'countries' => ['US'],
    'status' => 'ACTIVE',
    'media_type' => 'VIDEO',
    'search_type' => 'keyword_unordered',
];

$result = searchFacebookCreatives($paramsWithSocialFilters);

// Example 3: Live search polling (when scrapingJob.needStartPolling is true)
$initial = searchFacebookCreatives([
    'api_key' => 'YOUR_API_KEY',
    'limit' => 10,
    'offset' => 0,
    'keyword' => 'casino',
    'countries' => ['US'],
    'status' => 'ACTIVE',
]);

if ($initial && !empty($initial['data']['scrapingJob'])) {
    $scrapingJob = $initial['data']['scrapingJob'];

    if (!empty($scrapingJob['needStartPolling']) && !empty($scrapingJob['job_id'])) {
        $pollingResult = searchFacebookCreatives([
            'api_key' => 'YOUR_API_KEY',
            'isPolling' => true,
            'job_id' => $scrapingJob['job_id'],
            'limit' => 10,
            'offset' => 0,
        ]);
    }
}

// Note: If scrapingJob.status is "recently_completed" or "rejected", 
// the job will not be created and polling should not be started.

Search TikTok Creatives

Search for TikTok ads creatives with various filters. When results are low, the API can start Live Search and return a scrapingJob for polling.

If scrapingJob.needStartPolling is true, call the same endpoint with isPolling=true and job_id to receive new items. If status is recently_completed or rejected, no job is created and polling should not be started.

Live Search starts only when exactly one country is specified in the countries array.

Live Search starts only when a non-empty keyword is provided.

Request link

Parameter Data type Required Description
api_key String Yes Unique API key for request authentication.
limit Number No Number of items per page (10-100). Default: 10.
offset Number No Number of items to skip. Used for pagination. Default: 0.
keyword String No Search keyword to filter creatives by title or description.
countries Array No Array of country ISO-2 codes (e.g., ["US", "GB", "DE"]).
country_ids Array No Array of country IDs from /api/filters/countries endpoint. Takes precedence over countries.
languages Array No Array of language ISO codes (e.g., ["EN", "RU", "DE"]).
lang_ids Array No Array of language IDs from /api/filters/languages endpoint. Takes precedence over languages.
date_from String No Start date for filtering (format: Y-m-d, e.g., "2025-01-01").
date_to String No End date for filtering (format: Y-m-d, e.g., "2025-12-31").
sort_by String No Sort field: creation, activity, popularity.
sort_order String No Sort direction: asc or desc.
video_duration String No TikTok video duration filter: ALL, SHORT, MEDIUM, LONG.
isPolling Boolean No Enable polling for live search updates. Use with job_id.
lastId Number No Last creative ID received for incremental polling (optional).
perPage Number No Expected page size for low-results detection (12-96).
job_id String No Live search job id from scrapingJob. Required when isPolling=true.
Parameter Data type Description
status String Field indicating successful request execution ("success") or error ("error").
msg String Error message or additional request information.
code Number Response code, e.g., 200 for a successful request.
data Object Array of flow data matching the request.
└ format String Creative format (push, inpage, facebook, tiktok).
└ items Array Array of creative objects.
  └ id Number Unique creative identifier.
  └ title String Creative title text.
  └ description String Creative description text.
  └ category String Creative format/category (push, inpage, facebook, tiktok).
  └ country Object Country information object (code, name, iso_code_3).
    └ code String ISO 3166-1 alpha-2 country code (e.g., "US" for United States).
    └ name String Country name in English.
    └ iso_code_3 String ISO 3166-1 alpha-3 country code (e.g., "USA" for United States).
  └ file_size String Formatted total file size.
  └ icon_url String URL to the creative icon image.
  └ landing_url String Landing page URL.
  └ created_at String Creative creation date (Y-m-d format).
  └ advertising_networks Array Array of advertising network names.
  └ languages Array Array of language ISO codes.
  └ operating_systems Array Array of operating system values.
  └ browsers Array Array of browser names.
  └ devices Array Array of device types.
  └ main_image_url String URL to the main creative image.
  └ has_video Boolean Whether the creative contains video.
  └ video_url String URL to the video (if has_video is true).
  └ video_duration Number Video duration in seconds (if applicable).
  └ social_likes Number Number of social likes (for social ads).
  └ social_comments Number Number of social comments (for social ads).
  └ social_shares Number Number of social shares (for social ads).
  └ is_adult Boolean Whether the creative contains adult content.
  └ is_active Boolean Whether the creative is currently active.
└ pagination Object Pagination information object.
  └ total Number Total number of creatives matching the filters.
  └ limit Number Number of items per page.
  └ offset Number Current offset.
  └ has_more Boolean Whether more items are available.
  └ returned_count Number Number of items returned in this response.
└ filters_applied Object Object containing the filters that were applied.
└ scrapingJob Object Live search job object (present when live search is started or active).
  └ type String Live search type identifier (e.g., facebook_search).
  └ status String Job status: dispatched, running, post_processing, completed, failed, error, recently_completed, rejected.
  └ needStartPolling Boolean Whether the client should start polling for updates.
  └ needStopPolling Boolean Whether the client should stop polling.
  └ job_id String Job identifier for polling (absent when status is recently_completed or rejected).
  └ polling_interval_seconds Number Recommended polling interval in seconds.
  └ estimatedDuration Number Estimated duration in seconds (0 when completed or recently_completed).
  └ message String Additional status message from the server or parser.
  └ retry_after_seconds Number How long to wait before retrying when recently_completed/rejected (if provided).
  └ error String Error details (present when status is failed or error).
└ timestamp String Response timestamp in ISO 8601 format.
<?php

function searchTikTokCreatives($params = [])
{
    $ch = curl_init('https://spy.house/api/search/tiktok');

    curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
    curl_setopt($ch, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V4);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($params));

    $body = curl_exec($ch);
    $info = curl_getinfo($ch);

    curl_close($ch);

    if (!empty($info['http_code']) && $info['http_code'] == 200) {
        return json_decode($body, TRUE);
    }
    return null;
}

// Example 1: Basic search with API key
$params = [
    'api_key' => 'YOUR_API_KEY',
    'limit' => 20,
    'offset' => 0,
    'keyword' => 'casino',
    'countries' => ['US'],
];

// Example 2: TikTok filter (video_duration)
$paramsWithVideoDuration = [
    'api_key' => 'YOUR_API_KEY',
    'limit' => 20,
    'offset' => 0,
    'keyword' => 'casino',
    'countries' => ['US'],
    'video_duration' => 'SHORT',
];

$result = searchTikTokCreatives($paramsWithVideoDuration);

// Example 3: Live search polling (when scrapingJob.needStartPolling is true)
$initial = searchTikTokCreatives([
    'api_key' => 'YOUR_API_KEY',
    'limit' => 10,
    'offset' => 0,
    'keyword' => 'casino',
    'countries' => ['US'],
]);

if ($initial && !empty($initial['data']['scrapingJob'])) {
    $scrapingJob = $initial['data']['scrapingJob'];

    if (!empty($scrapingJob['needStartPolling']) && !empty($scrapingJob['job_id'])) {
        $pollingResult = searchTikTokCreatives([
            'api_key' => 'YOUR_API_KEY',
            'isPolling' => true,
            'job_id' => $scrapingJob['job_id'],
            'limit' => 10,
            'offset' => 0,
        ]);
    }
}

// Note: If scrapingJob.status is "recently_completed" or "rejected", 
// the job will not be created and polling should not be started.

Transferring funds

Request link

Parameter Data type Required Description
api_key String Yes Unique API key for request authentication.
amount Number Yes Transfer amount (minimum 10 USD).
email String Yes Recipient email for the transfer. Must be valid.
Parameter Data type Description
status String Field indicating successful request execution ("success") or error ("error").
msg String Error message or additional request information.
code Number Response code, e.g., 200 for a successful request.
transaction_number String Unique transaction number associated with the transfer.
<?php


    function api_request($data = [])
    {
        $ch = curl_init('https://spy.house/api/accounts/transfer_funds');

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
        curl_setopt($ch, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V4);
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

        $body = curl_exec($ch);
        $info = curl_getinfo($ch);

        curl_close($ch);

        if ( ! empty($info['http_code']) && $info['http_code'] == 200) {
            return json_decode($body, TRUE);
        }
    }


    $body_request = [
        'api_key' => 'YOUR_API_KEY',
        'amount' => 100,
        'email' => '[email protected]'
    ];


    $api_request = api_request($body_request);
    if ( ! empty($api_request['status'])) {
        echo '<pre>';
        print_r($api_request);
        echo '</pre>';
    }

Retrieving account balance

Request link

Parameter Data type Required Description
api_key String Yes Unique API key for request authentication.
Parameter Data type Description
status String Field indicating successful request execution ("success") or error ("error").
msg String Error message or additional request information.
code Number Response code, e.g., 200 for a successful request.
balance Number Current user account balance.
<?php


    function api_request($data = [])
    {
        $ch = curl_init('https://spy.house/api/accounts/balance');

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
        curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
        curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
        curl_setopt($ch, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V4);
        curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));

        $body = curl_exec($ch);
        $info = curl_getinfo($ch);

        curl_close($ch);

        if ( ! empty($info['http_code']) && $info['http_code'] == 200) {
            return json_decode($body, TRUE);
        }
    }


    $body_request = [
        'api_key' => 'YOUR_API_KEY'
    ];


    $api_request = api_request($body_request);
    if ( ! empty($api_request['status'])) {
        echo '<pre>';
        print_r($api_request);
        echo '</pre>';
    }