Buy Proxy Servers | Fast & Affordable

POST https://iphtml.com/v1/crawl/search

1. Create SERP Query Task

Submit keywords and other parameters to create an asynchronous search engine scraping task. Once completed, the result will be returned via the serp_notify webhook.

Request Parameters (Form-Data / x-www-form-urlencoded)

Parameter	Type	Required	Default	Description
`keyword`	String(255)	Yes	-	The search keyword to query
`domain`	String(255)	Yes	-	The search url to query (pass URL if engine is website \| amazon_bestsellers_scraper \| tiktok)
`page`	Integer	Yes	1	The page number of the search results to query
`engine`	String	Yes	google	Search engine ( google \| bing \| website \| amazon_bestsellers_scraper \| amazon_product_details \| amazon_product_search \| tiktok )
`language`	String	Yes	en	Language code (en \| zh \| ja \| ko \| fr \| ar \| he \| de \| pt \| es)
`device`	String	Yes	desktop	Device type (desktop \| mobile)
`format`	String	Yes	json	Data return format ( html \| json \| xml ) ( pass html if engine is website )
`postbackurl`	String	No	-	Webhook callback URL to receive results after task completion

Success Response Example

{
    "retCode": 200,
    "task_id": "52388bccd4d3d2b3934bd265cdf71845",
    "remaining": 29987,
    "retMsg": "Task queued"
}

GET https://iphtml.com/v1/account/detail

2. Query account details

Query the current account details, including balance, remaining quotas and expiration times for each service.

Response Parameters

Top-level Fields

Field	Type	Description
`retCode`	Integer	API request status code, 200 means success
`retMsg`	String	Status message
`User`	Object	User account information
`Scraping`	Object	Web scraping service quota information
`Video`	Object	Video service quota information

User Object Fields

Field	Type	Description
`balance`	Float	Account balance

Scraping Object Fields

Field	Type	Description
`remaining`	Integer	Remaining available quota
`expire_time`	String	Quota expiration time (Format: DD-MM-YY)

Video Object Fields

Field	Type	Description
`remaining`	Float	Remaining available duration (seconds)
`expire_time`	String	Quota expiration time (Format: DD-MM-YY)

Success Response Example

{
        "retCode": 200,
        "retMsg": "Success",
        "User": {
            "balance": 433.1
        },
        "Scraping": {
            "remaining": 16924,
            "expire_time": "26-05-24"
        },
        "Video": {
            "remaining": 50.91,
            "expire_time": "26-05-28"
        }
    }

GET https://iphtml.com/v1/crawl/tasks

3. Check Task Progress

Query the current execution progress and status of the specified task.

Request Parameters

Parameter	Type	Required	Description
`task_id`	String	Yes	The `task_id` returned from the /api/serp endpoint (task_no)

Response Parameters

Top-Level Fields

Field	Type	Description
`retCode`	Integer	API request status code, 200 means success
`retMsg`	String	Status message
`status`	Integer	Task execution status code `1` - Processing `2` - Success `3` - Failed
`success`	Boolean	success status code
`retData`	Object\|null	Task result data, only returned when `status=2`

retData Object Fields (By Engine Type)

Depending on the engine type, the retData structure varies:

Common Fields

Field	Type	Description
`status`	String	Task execution result: success / error
`code`	Integer	Status code, 0 means success
`message`	String	Status description message
`request`	Object	Original request parameter details

Search Engine (Google | Bing) Response Fields

Field	Type	Description
`pagination`	Object	Pagination information
`data`	Array	Search result data (two-dimensional array, grouped by page)
`relatedKeywords`	Array	Related search keywords list
`sections`	Array	Search result sections (ads, featured snippets, related searches, etc.)

Amazon(Amazon Bestsellers Scraper | Amazon Product Search) Search Response Fields

Field	Type	Description
`pagination`	Object	Pagination information
`data`	Array	Product listing data

Amazon Product Details Response Fields

Field	Type	Description
`data`	Object	Basic product information
`variations`	Array	Product variations (color, size, etc.)
`features`	Array	Product features list
`images`	Array	Product images list
`details`	Array	Product detailed specifications
`seller`	Object	Seller information
`reviews`	Array/Object	Product reviews data
`pricing`	Object	Product pricing information
`metadata`	Array	Product metadata information

Amazon Reviews Response Fields

Field	Type	Description
`pagination`	Object	Pagination information
`data`	Object	Basic product information
`reviews`	Array	Reviews list
`filters`	Array	Review filters
`rating_breakdown`	Array	Rating breakdown statistics

TikTok Response Fields

Field	Type	Description
`profile`	Object	User profile information
`data`	Array	Top videos list
`pinned_posts`	Array	Pinned posts list
`top_posts_data`	Array	Top posts data

request Object Fields

Field	Type	Description
`platform`	String	Search engine platform (google / bing / website)
`type`	String	Query type (search, etc.)
`keyword`	String	Search keyword
`page`	Integer	Search page number
`pageSize`	String	Results per page
`country`	String	Country/region code
`language`	String	Language code
`device`	String	Device type (desktop / mobile)
`url`	String	Actual scraped URL

pagination Object Fields

Field	Type	Description
`total`	Integer	Total pages
`page`	Integer	Current page number
`pageSize`	Integer	Results per page
`hasNextPage`	Boolean	Whether there is a next page
`nextPageUrl`	String	URL of the next page
`nextPageToken`	String	Token identifier for the next page

data Array Item Fields (Organic Search Results)

Field	Type	Description
`type`	String	Result type, e.g. `organic`
`rank`	Integer	Current ranking position
`title`	String	Search result title
`description`	String	Search result description
`url`	String	Search result URL
`displayUrl`	String	Display URL (shortened form)
`domain`	String	Domain name
`metadata`	Object	Metadata (site_name, cite, etc.)
`relatedItems`	Array	Related sub-links (sitelinks)

sections Array Item Fields

Field	Type	Description
`type`	String	Section type: `ads` - Ads `featured_snippet` - Featured Snippet `related_searches_block` - Related Searches Block `related_content` - Related Content
`title`	String	Section title
`items`	Array	List of items within the section, fields include: `title`, `description`, `url`, `domain`, `metadata`, etc.

relatedKeywords Array Item Fields

Field	Type	Description
`keyword`	String	Related search keyword
`title`	String	Keyword title
`url`	String	Related search URL
`source`	String	Source identifier, e.g. `inline_rs`

Success Response Example

{
        "retCode": 200,
        "retMsg": "Success",
        "success": true,
        "status": 2,
        "retData": {
            "status": "success",
            "code": 0,
            "message": "OK",
            "request": {
                "platform": "bing",
                "type": "search",
                "keyword": "BMW X6",
                "page": 1,
                "pageSize": "",
                "country": "",
                "language": "en",
                "device": "desktop",
                "url": "https://www.bing.com/search?q=BMW+X6&first=11"
            },
            "pagination": {
                "total": 3,
                "page": 1,
                "pageSize": 10,
                "hasNextPage": true,
                "nextPageUrl": "https://www.bing.com/search?q=BMW+X6&rdr=1&rdrig=3C689FE2471840948C6A685CCF91AEDD&FPIG=0346B39B501A44D5935E1B14A4619E1D&first=7&FORM=PERE",
                "nextPageToken": "7"
            },
            "data": [
                [
                    {
                        "type": "organic",
                        "rank": 1,
                        "title": "2027 BMW X6 Luxury Midsize Coupe SUV | All Models & Pricing",
                        "description": "Discover the perfect blend of rugged crossover design, driving dynamics and aggressive aesthetics of the 2027 BMW X6 Coupe SUV.",
                        "url": "https://www.bmwusa.com/vehicles/x-series/x6/bmw-x6.html",
                        "displayUrl": "https://www.bmwusa.com › vehicles › x-series",
                        "domain": "bmwusa.com",
                        "metadata": {
                            "site_name": "BMW USA",
                            "cite": "https://www.bmwusa.com › vehicles › x-series"
                        },
                        "relatedItems": [
                            {
                                "title": "BMW USA",
                                "url": "https://www.bmwusa.com/vehicles/x-series/x6/bmw-x6.html"
                            }
                        ]
                    }
                ]
            ],
            "relatedKeywords": [
                {
                    "keyword": "BMW x6 for sale",
                    "title": "BMW x6 for sale",
                    "url": "https://www.bing.com/search?q=BMW+x6+for+sale&FORM=QSRE9",
                    "source": "inline_rs"
                }
            ],
            "sections": [
                {
                    "type": "ads",
                    "title": "Sponsored",
                    "items": [...]
                },
                {
                    "type": "featured_snippet",
                    "title": "",
                    "items": [...]
                },
                {
                    "type": "related_searches_block",
                    "title": "Deep dive into BMW X6",
                    "items": [...]
                }
            ]
        }
    }

POST https://iphtml.com/v1/crawl/list

4. Get Task History List

Paginate through the history of submitted search task records and their statuses.

Request Parameters

Parameter	Type	Required	Description
`page`	Integer	Yes	Page number (returns 20 records per page)
`page_size`	Integer	Yes	Display quantity

Success Response Example

Note: status 0 represents pending, 1 represents processing ,2 means success, 3 means failure (includes error_msg). Upon success, result_link will be provided.

{
    "retCode": 200,
    "orderList":[
        {
            "task_no": "52388bccd4d3d2b3934bd265cdf71845",
            "keyword": "Nainai Champagne",
            "status": 3,
            "responses_used": 0,
            "create_time": 1775895587,
            "finish_time": 1775895590,
            "error_msg": "Bing returned challenge page",
            "result_link": ""
        },
        {
            "task_no": "ead9dd18b2efe59d297101697bff7894",
            "keyword": "History",
            "status": 2,
            "responses_used": 1,
            "create_time": 1774952513,
            "finish_time": 1774952514,
            "error_msg": null,
            "result_link": "http://www.domain.com/site/getlink?paremeter=..."
        }
    ],
    "retMsg": "success"
}

POST User postbackurl

5. User Callback Notification

If postbackurl is provided when creating a task, the system sends a POST JSON notification after the task reaches a final state.

Callback Payload Field Description

Task Status Fields (Top-Level)

Field	Type	Description
`task_id`	String	Unique task identifier, same as the `task_id` returned when creating the task
`success`	Boolean	Whether the task executed successfully: `true` - Task completed successfully `false` - Task execution failed
`status`	String	Task execution status code: `"2"` - Success `"3"` - Failed
`error`	String\|null	Error message, only present when `success=false`
`retData`	Object\|null	Task result data, only present when `success=true`

retData Object Fields (By Engine Type)

Depending on the engine type, the retData structure varies:

Common Fields

Field	Type	Description
`status`	String	Task execution result: success / error
`code`	Integer	Status code, 0 means success
`message`	String	Status description message
`request`	Object	Original request parameter details

Search Engine (Google | Bing) Response Fields

Field	Type	Description
`pagination`	Object	Pagination information
`data`	Array	Search result data (two-dimensional array, grouped by page)
`relatedKeywords`	Array	Related search keywords list
`sections`	Array	Search result sections (ads, featured snippets, related searches, etc.)

Amazon(Amazon Bestsellers Scraper | Amazon Product Search) Search Response Fields

Field	Type	Description
`pagination`	Object	Pagination information
`data`	Array	Product listing data

Amazon Product Details Response Fields

Field	Type	Description
`data`	Object	Basic product information
`variations`	Array	Product variations (color, size, etc.)
`features`	Array	Product features list
`images`	Array	Product images list
`details`	Array	Product detailed specifications
`seller`	Object	Seller information
`reviews`	Array/Object	Product reviews data
`pricing`	Object	Product pricing information
`metadata`	Array	Product metadata information

Amazon Reviews Response Fields

Field	Type	Description
`pagination`	Object	Pagination information
`data`	Object	Basic product information
`reviews`	Array	Reviews list
`filters`	Array	Review filters
`rating_breakdown`	Array	Rating breakdown statistics

TikTok Response Fields

Field	Type	Description
`profile`	Object	User profile information
`data`	Array	Top videos list
`pinned_posts`	Array	Pinned posts list
`top_posts_data`	Array	Top posts data

request Object Fields

Field	Type	Description
`platform`	String	Search engine platform (google / bing / website)
`type`	String	Query type
`keyword`	String	Search keyword
`page`	Integer	Search page number
`language`	String	Language code
`device`	String	Device type (desktop / mobile)
`url`	String	Actual scraped URL

pagination Object Fields

Field	Type	Description
`total`	Integer	Total pages
`page`	Integer	Current page number
`pageSize`	Integer	Results per page
`hasNextPage`	Boolean	Whether there is a next page
`nextPageUrl`	String	URL of the next page
`nextPageToken`	String	Token identifier for the next page

sections Array Item Fields

Field	Type	Description
`type`	String	Section type: `ads` - Ads `featured_snippet` - Featured Snippet `related_searches_block` - Related Searches Block `related_content` - Related Content
`title`	String	Section title
`items`	Array	List of items within the section

Success Callback Payload Example

{
        "task_id": "52388bccd4d3d2b3934bd265cdf71845",
        "success": true,
        "status": "2",
        "retData": {
            "status": "success",
            "code": 0,
            "message": "OK",
            "request": {
                "platform": "bing",
                "type": "search",
                "keyword": "BMW X6",
                "page": 1,
                "language": "en",
                "device": "desktop",
                "url": "https://www.bing.com/search?q=BMW+X6&first=11"
            },
            "pagination": {
                "total": 3,
                "page": 1,
                "pageSize": 10,
                "hasNextPage": true,
                "nextPageUrl": "https://www.bing.com/search?q=BMW+X6&...",
                "nextPageToken": "7"
            },
            "data": [
                [
                    {
                        "type": "organic",
                        "rank": 1,
                        "title": "2027 BMW X6 Luxury Midsize Coupe SUV | All Models & Pricing",
                        "description": "Discover the perfect blend of rugged crossover design...",
                        "url": "https://www.bmwusa.com/vehicles/x-series/x6/bmw-x6.html",
                        "displayUrl": "https://www.bmwusa.com › vehicles › x-series",
                        "domain": "bmwusa.com"
                    }
                ]
            ],
            "relatedKeywords": [
                {
                    "keyword": "BMW x6 for sale",
                    "title": "BMW x6 for sale",
                    "url": "https://www.bing.com/search?q=BMW+x6+for+sale&FORM=QSRE9",
                    "source": "inline_rs"
                }
            ],
            "sections": [
                {
                    "type": "ads",
                    "title": "Sponsored",
                    "items": [...]
                }
            ]
        }
    }

Failed Callback Payload Example

{
        "task_id": "52388bccd4d3d2b3934bd265cdf71845",
        "success": false,
        "status": "3",
        "error": "Download failed, please try again later."
    }

INFO Error Codes Reference

API Error Codes List

All APIs return the following JSON format. retCode identifies the request result:

            {
                "retCode": 200,
                "retMsg": "Success"
            }

Note: Except for the /v1/crawl/download endpoint, all endpoints return HTTP 200 even on business errors. Use retCode to distinguish success from failure.

Success Codes

retCode	Message	Description
`200`	Success / Task queued successfully	Request successful / Task queued

Parameter Validation Errors

retCode	Message	Description
`10001`	Missing API key	Missing API Key (x-api-key header is empty)
`10002`	Please enter a keyword	Keyword is empty (required for search engines)
`10003`	Missing search engine	Missing engine parameter (engine is empty)
`10004`	Missing language	Missing language parameter (language is empty)
`10005`	Missing device	Missing device parameter (device is empty)
`10006`	Missing format	Missing format parameter (format is empty)
`10008`	Keyword length cannot exceed 255 characters	Keyword length exceeds 255 characters
`10010`	Invalid search engine	Engine parameter not in allowed list
`10011`	Invalid language	Language code not in allowed list (en/zh/ja/ko/fr/ar/he/de/pt/es)
`10012`	Invalid device	Device parameter not in allowed list (desktop/mobile)
`10013`	Invalid format	Format parameter not in allowed list (html/json/xml)
`10014`	Please enter the URL of the Amazon Best Sellers category	Invalid Amazon Best Sellers category URL
`10015`	Please enter the URL of the Amazon product page	Invalid Amazon product page URL (domain is not amazon.*)
`10016`	Please enter the URL of the Amazon Product Reviews category	Invalid Amazon reviews URL (path doesn't contain /product-reviews/)
`10017`	Please enter the URL of the TikTok page	Invalid TikTok URL (domain is not *.tiktok.com)
`10018`	Callback URL length cannot exceed 255 characters	Callback URL (postbackurl) length exceeds 255 characters
`10019`	Callback URL must be a valid HTTPS URL	Callback URL (postbackurl) is not a valid HTTPS URL
`10020`	Domain length cannot exceed 255 characters	Domain length exceeds 255 characters
`10023`	Please enter a domain	Domain is empty (required for website-type engines)
`10024`	Domain must be a valid HTTP/HTTPS URL	Domain is not a valid HTTP/HTTPS URL
`10025`	Keyword must contain valid text	Keyword must contain valid letters or numbers (symbols-only not supported)
`10026`	Keyword cannot be a URL	Keyword cannot be a URL address

Authentication & User Errors

retCode	Message	Description
`10021`	Invalid API key	Invalid API Key (no matching user in database)

Quota & Resource Errors

retCode	Message	Description
`10014`	Quota exceeded	Quota exhausted (remaining count is 0)
`10015`	No active plan available, please purchase first	No active plan (no valid order to deduct from)
`10004`	Task not found	Task not found (no record matching task_id)
`10006`	No data	No data (order list is empty)

System Errors

retCode	Message	Description
`10099`	Internal server error	Internal server error (unknown exception)

Download Endpoint HTTP Status (Only /v1/crawl/download)

The download endpoint uses standard HTTP status codes instead of retCode:

HTTP Code	Description	Trigger Scenario
`302`	Redirect to download link	Task completed, file available for download
`400`	Bad Request	task_id is invalid or empty
`401`	Unauthorized	API Key is missing or invalid
`404`	Not Found	Task not found or not completed (no download link)
`405`	Method Not Allowed	Non-GET method used on download endpoint
`500`	Internal Server Error	Database exception or system error

SERP API Documentation

🔑 Authentication

1. Create SERP Query Task

Request Parameters (Form-Data / x-www-form-urlencoded)

Success Response Example

2. Query account details

Response Parameters

Top-level Fields

User Object Fields

Scraping Object Fields

Video Object Fields

Success Response Example

3. Check Task Progress

Request Parameters

Response Parameters

Top-Level Fields

retData Object Fields (By Engine Type)

Common Fields

Search Engine (Google | Bing) Response Fields

Amazon(Amazon Bestsellers Scraper | Amazon Product Search) Search Response Fields

Amazon Product Details Response Fields

Amazon Reviews Response Fields

TikTok Response Fields

request Object Fields

pagination Object Fields

data Array Item Fields (Organic Search Results)

sections Array Item Fields

relatedKeywords Array Item Fields

Success Response Example

4. Get Task History List

Request Parameters

Success Response Example

5. User Callback Notification

Callback Payload Field Description

Task Status Fields (Top-Level)

retData Object Fields (By Engine Type)

Common Fields

Search Engine (Google | Bing) Response Fields

Amazon(Amazon Bestsellers Scraper | Amazon Product Search) Search Response Fields

Amazon Product Details Response Fields

Amazon Reviews Response Fields

TikTok Response Fields

request Object Fields

pagination Object Fields

sections Array Item Fields

Success Callback Payload Example

Failed Callback Payload Example

API Error Codes List

Success Codes

Parameter Validation Errors

Authentication & User Errors

Quota & Resource Errors

System Errors

Download Endpoint HTTP Status (Only /v1/crawl/download)