Overview
The Traffic & Market API provides website traffic metrics, traffic sources and destinations, and audience data. Use it to compare websites and add traffic and audience data to reports, dashboards, or applications.
Jump to Available dataAvailable data
Jump to Get accessGet access
You need access to the Traffic & Market API and a Version 4 API key. For help setting up API access, refer to API access.
Traffic & Market API v4 uses the same API units as other Semrush APIs.
Jump to AuthorizationAuthorization
You’ll find your keys in the API keys section of your Semrush profile. For a new integration, create a new Version 4 key.
Include your API key in the Authorization header of every request:
curl -H 'Authorization: Apikey YOUR_API_KEY' \
'https://api.semrush.com/apis/v4/traffic-market/v1/traffic/trend/monthly?url=example.com&scope=ROOT_DOMAIN&date_from=2024-01&date_to=2024-03&fields=visitors,visits'Jump to Response formatResponse format
All Traffic & Market endpoints support JSON and CSV. Set format=json or format=csv. The default is JSON.
Successful JSON responses contain:
meta: Request details and response metadata, includingrequest_id,status_code, andsuccess.data: Results. List endpoints return an array.
CSV responses use semicolons to separate columns. The endpoint reference lists the response fields and includes examples of both formats.
Where supported, use fields to select response fields. Identity fields, such as a page URL or demographic group, are returned automatically. Supported fields vary by endpoint.
Jump to Request parametersRequest parameters
The parameters depend on the report:
- Target: Trend reports (Daily, Weekly, and Monthly) and traffic breakdowns use
urlandscope. Supported scopes vary by endpoint. Audience reports and Domain Categories usedomain. - Time period: Trend reports use
date_fromanddate_toin theYYYY-MMformat. The range can’t start before2017-01or exceed 12 months. Other dated reports usemonthin the same format. - Filters: Use
device_typeorcountrywhere supported. Audience reports supportcountryas their only geographic filter. Some traffic reports also supportsubregionandstate. These three geographic filters are mutually exclusive. - Industry: Sources, Destinations, and Visited Domains support a
categoriesfilter. - Sorting and pagination: List reports that support these options use
order_by,direction,limit, andoffset.
Check the API reference for each endpoint’s required parameters, defaults, supported values, and limits.
Jump to Data updatesData updates
The update schedule depends on the report:
Weekly trends include only complete weeks. Monthly trends don’t accept the current, incomplete month. For date restrictions and forecast options, refer to the API reference.
Jump to Error handlingError handling
When a request fails, the API returns a structured error response instead of data. Check the HTTP status and the error object. If the response includes error.retryable, don’t retry requests marked false.
{
"meta": {
"success": false,
"status_code": 400,
"request_id": "4fb1773ec2a8d61a0407f464599f897c"
},
"error": {
"code": 400,
"message": "Bad Request",
"retryable": false,
"details": [
{
"field": "month",
"message": "month must be in YYYY-MM format"
}
]
}
}For a field validation error, error.details is an array of objects with field and message. details is omitted when the error is not tied to a request field.
meta.successfalse.meta.status_codemeta.request_iderror.codeerror.messageerror.retryablefalse.error.detailsfield and message. Omitted when the error is not tied to a request field.Use this table to identify the cause of an error and what to do next:
445, 446, 447An empty result doesn’t always mean an error:
- Domain Categories returns an empty list for an unknown domain or a domain with no assigned categories.
When contacting support, include the request, response, and meta.request_id. For more help, refer to Troubleshooting.
Jump to FAQFAQ
Jump to How are API requests charged?How are API requests charged?
Most list and trend reports charge API units per line returned. Audience demographic reports charge per request. Check the price for each endpoint in the API reference.
Jump to What happens to my Trends API unit pack?What happens to my Trends API unit pack?
Your Trends API unit pack will be converted to API units that you can use with Traffic & Market API v4 and other Semrush APIs.
Jump to How do I request daily or weekly data?How do I request daily or weekly data?
Set date_from and date_to in the YYYY-MM format to select the months to cover. Use Daily for results grouped by day or Weekly for results grouped by week.
Jump to Can I analyze the combined audience of several domains?Can I analyze the combined audience of several domains?
Use Visited Domains to find other sites visited by an audience built from multiple domains. Pass the domains in domain and use operation to combine their audiences with UNION, find their overlap with INTERSECTION, or apply DIFFERENCE. Check the endpoint’s selected_domains rules when choosing the domains for the operation.
Last updated: November 20, 2026