# Historical Bulk Traffic Estimation **API:** Data API **Endpoint:** `POST /v1/beta/dataforseo/dataforseo_labs/google/historical_bulk_traffic_estimation/live` **Tags:** DataForSEO Estimated organic traffic for many domains at each point in the available history - the time series behind `post_dataforseo_labs_google_bulk_traffic_estimation_live`. This one takes no limit parameter, but it is priced per call rather than per item, so send the whole list at once. Wrapped in DataForSEO's envelope: data in `tasks[0].result`, outcome in `tasks[0].status_code` - a rejected request still returns HTTP 200. ⚠️ Response size multiplies domains by dates; keep both lists short. Available dates come from `get_dataforseo_labs_google_available_history`. ### Pricing reference - Metering: Reported response cost. - Reference request estimate: USD 0.1356. - Reference customer multiplier: 1.0. Do not apply it again to a settled customer amount. Reference metadata only, not an account quote, a guaranteed price or a spending cap. Resource credits are not Felo credits. Final charges follow Felo billing records. ## Base URL - `https://openapi.felo.ai` ## Authentication - `FeloBearerAuth` (http bearer, bearer format Felo API Key) - `FeloApiKey` (apiKey in header `X-API-Key`) ## Request body Required: **no** ### application/json Schema: ```json { "type": "array", "items": { "type": [ "object", "null" ], "oneOf": [ { "type": "object", "properties": { "targets": { "type": "array", "items": { "type": "string" }, "description": "target domains and subdomains
required field
you can specify domains and subdomains in this field;
domains and subdomains should be specified without https:// and www.;
you can set up to 1000 domains or subdomains" }, "location_name": { "type": [ "string", "null" ], "description": "full name of the location
if you use this field, you don't have to specify location_code
you can receive the list of available locations with their location_name by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available locations
example:
United Kingdom" }, "location_code": { "type": [ "integer", "null" ], "description": "location code
if you use this field, you don't have to specify location_name
you can receive the list of available locations with their location_code by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available locations
example:
2840" }, "language_name": { "type": [ "string", "null" ], "description": "full name of the language
if you use this field, you don’t need to specify language_code
you can receive the list of available languages with their language_name by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available languages
example:
English" }, "language_code": { "type": [ "string", "null" ], "description": "language code
if you use this field, you don’t need to specify language_name
you can receive the list of available languages with their language_code by making a separate request to the
https://api.dataforseo.com/v3/dataforseo_labs/locations_and_languages
ignore this field to get the results for all available languages
example:
en" }, "date_from": { "type": [ "string", "null" ], "description": "starting date of the time range
optional field
if you don't specify this field, the data will be provided for the previous 12 months
minimal possible value: 2020-10-01
date format: \"yyyy-mm-dd\"" }, "date_to": { "type": [ "string", "null" ], "description": "ending date of the time range
optional field
if you don't specify this field, the today's date will be used by default;
date format: \"yyyy-mm-dd\"
example:
\"2021-04-01\"" }, "ignore_synonyms": { "type": [ "boolean", "null" ], "description": "ignore highly similar keywords
optional field
if set to_true only core keywords will be returned, all highly similar keywords will be excluded;
default value: falsen" }, "item_types": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "display results by item type
optional field
indicates the type of search results included in the response;
Note: if the item_types array contains item types that are different from organic, the results will be ordered by the first item type in the array;
possible values:
[\"organic\", \"paid\", \"featured_snippet\", \"local_pack\"]
default value:
[\"organic\", \"paid\"]" }, "tag": { "type": [ "string", "null" ], "description": "user-defined task identifier
optional field
the character limit is 255
you can use this parameter to identify the task and match it with the result
you will find the specified tag value in the data object of the response" } }, "example": [ { "targets": [ "dataforseo.com", "cnn.com", "forbes.com" ], "location_code": 2840, "language_code": "en", "date_from": "2021-01-01", "date_to": "2021-03-29", "item_types": [ "organic", "paid" ] } ] } ] }, "example": [ { "targets": [ "dataforseo.com", "cnn.com", "forbes.com" ], "location_code": 2840, "language_code": "en", "date_from": "2021-01-01", "date_to": "2021-03-29", "item_types": [ "organic", "paid" ] } ] } ``` ## Responses ### 200 — Successful operation Headers: - `X-Request-Id` (string) — Request identifier to include when contacting Felo support. **application/json** Schema: object | null ```json { "type": [ "object", "null" ], "oneOf": [ { "$ref": "#/components/schemas/Response36Afe1097B20_DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveResponseInfo" } ] } ``` ### 400 — The request could not be processed. Check the request parameters. ### 401 — A valid Felo API key is required. ### 402 — The request cannot proceed because a billing requirement is not met. ### 403 — The account is not permitted to perform this operation. ### 429 — A request or spending limit has been reached. ### 502 — The service could not complete the request. ### 503 — The API or billing service is temporarily unavailable. ### 504 — The service timed out while processing the request. ### default — Error response; upstream passthrough responses may use provider formats **application/json** Schema: ```json {} ``` ## Schema definitions ### Response36Afe1097B20_BaseResponseInfo `#/components/schemas/Response36Afe1097B20_BaseResponseInfo` ```json { "properties": { "version": { "type": [ "string", "null" ], "description": "the current version of the API" }, "status_code": { "type": [ "integer", "null" ], "description": "general status code\nyou can find the full list of the response codes here" }, "status_message": { "type": [ "string", "null" ], "description": "general informational message\nyou can find the full list of general informational messages here" }, "time": { "type": [ "string", "null" ], "description": "total execution time, seconds" }, "cost": { "type": [ "number", "null" ], "description": "total tasks cost, USD", "format": "double" }, "tasks_count": { "type": [ "integer", "null" ], "description": "the number of tasks in the tasks array", "format": "int64" }, "tasks_error": { "type": [ "integer", "null" ], "description": "the number of tasks in the tasks array returned with an error", "format": "int64" } } } ``` ### Response36Afe1097B20_BaseResponseTaskInfo `#/components/schemas/Response36Afe1097B20_BaseResponseTaskInfo` ```json { "properties": { "id": { "type": [ "string", "null" ], "description": "task identifier\nunique task identifier in our system in the UUID format" }, "status_code": { "type": [ "integer", "null" ], "description": "status code of the task\ngenerated by DataForSEO, can be within the following range: 10000-60000\nyou can find the full list of the response codes here" }, "status_message": { "type": [ "string", "null" ], "description": "informational message of the task\nyou can find the full list of general informational messages here" }, "time": { "type": [ "string", "null" ], "description": "execution time, seconds" }, "cost": { "type": [ "number", "null" ], "description": "total tasks cost, USD", "format": "double" }, "result_count": { "type": [ "integer", "null" ], "description": "number of elements in the result array", "format": "int64" }, "path": { "type": [ "array", "null" ], "items": { "type": [ "string", "null" ] }, "description": "URL path" }, "data": { "type": [ "object", "null" ], "additionalProperties": { "type": [ "object", "null" ] }, "description": "contains the same parameters that you specified in the POST request" } } } ``` ### Response36Afe1097B20_DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveItem `#/components/schemas/Response36Afe1097B20_DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveItem` ```json { "type": "object", "properties": { "se_type": { "type": [ "string", "null" ], "description": "search engine type" }, "target": { "type": [ "string", "null" ], "description": "target domain in a POST array" }, "metrics": { "type": [ "object", "null" ], "oneOf": [ { "$ref": "#/components/schemas/Response36Afe1097B20_HistoricalMetricsBundleInfo" } ], "description": "traffic data relevant to the specified domain" } } } ``` ### Response36Afe1097B20_DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveResponseInfo `#/components/schemas/Response36Afe1097B20_DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveResponseInfo` ```json { "type": "object", "allOf": [ { "$ref": "#/components/schemas/Response36Afe1097B20_BaseResponseInfo" }, { "type": "object", "properties": { "tasks": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "oneOf": [ { "$ref": "#/components/schemas/Response36Afe1097B20_DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveTaskInfo" } ] }, "description": "array of tasks" } } } ] } ``` ### Response36Afe1097B20_DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveResultInfo `#/components/schemas/Response36Afe1097B20_DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveResultInfo` ```json { "type": "object", "properties": { "se_type": { "type": [ "string", "null" ], "description": "search engine type" }, "location_code": { "type": [ "integer", "null" ], "description": "location code in a POST array
if there is no data, then the value is null" }, "language_code": { "type": [ "string", "null" ], "description": "language code in a POST array
if there is no data, then the value is null" }, "total_count": { "type": [ "integer", "null" ], "description": "total amount of results in our database relevant to your request", "format": "int64" }, "items_count": { "type": [ "integer", "null" ], "description": "the number of results returned in the items array", "format": "int64" }, "items": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "oneOf": [ { "$ref": "#/components/schemas/Response36Afe1097B20_DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveItem" } ] }, "description": "array of items with relevant traffic estimation data" } } } ``` ### Response36Afe1097B20_DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveTaskInfo `#/components/schemas/Response36Afe1097B20_DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveTaskInfo` ```json { "type": "object", "allOf": [ { "$ref": "#/components/schemas/Response36Afe1097B20_BaseResponseTaskInfo" }, { "type": "object", "properties": { "result": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "oneOf": [ { "$ref": "#/components/schemas/Response36Afe1097B20_DataforseoLabsGoogleHistoricalBulkTrafficEstimationLiveResultInfo" } ] }, "description": "array of results" } } } ] } ``` ### Response36Afe1097B20_HistoricalMetricsBundleInfo `#/components/schemas/Response36Afe1097B20_HistoricalMetricsBundleInfo` ```json { "type": "object", "properties": { "organic": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "oneOf": [ { "$ref": "#/components/schemas/Response36Afe1097B20_HistoricalMetricsInfo" } ] }, "description": "traffic data from organic search" }, "paid": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "oneOf": [ { "$ref": "#/components/schemas/Response36Afe1097B20_HistoricalMetricsInfo" } ] }, "description": "traffic data from paid search" }, "local_pack": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "oneOf": [ { "$ref": "#/components/schemas/Response36Afe1097B20_HistoricalMetricsInfo" } ] }, "description": "traffic data from the local pack results in SERP" }, "featured_snippet": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "oneOf": [ { "$ref": "#/components/schemas/Response36Afe1097B20_HistoricalMetricsInfo" } ] }, "description": "traffic data from the featured snippet results in Google SERP" } } } ``` ### Response36Afe1097B20_HistoricalMetricsInfo `#/components/schemas/Response36Afe1097B20_HistoricalMetricsInfo` ```json { "type": "object", "properties": { "year": { "type": [ "integer", "null" ], "description": "year for which the data is provided" }, "month": { "type": [ "integer", "null" ], "description": "month for which the data is provided" }, "etv": { "type": [ "number", "null" ], "description": "estimated traffic volume
estimated organic monthly traffic to the domain
calculated as the product of CTR (click-through-rate) and search volume values of all keywords the domain ranks for
learn more about how the metric is calculated in this help center article" }, "count": { "type": [ "integer", "null" ], "description": "total count of organic SERPs that contain the domain", "format": "int64" } } } ```