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

Data
What you can retrieve
API methods
Traffic trends
Visits, unique visitors, engagement metrics, and traffic channels by day, week, or month.
Website sections
Traffic metrics for individual pages, subdomains, and subfolders.
Traffic flows
Sources that bring traffic to a target and destinations visited after it.
Geographic distribution
Traffic metrics grouped by country, geographic subregion, or US state.
Audience demographics
Visitor distributions by age and sex, education, household size, income, and occupation.
Audience interests and overlap
Interest categories, social media platforms, and other domains visited by a target audience.

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:

Monthly traffic request
Shell
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, including request_id, status_code, and success.
  • 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 url and scope. Supported scopes vary by endpoint. Audience reports and Domain Categories use domain.
  • Time period: Trend reports use date_from and date_to in the YYYY-MM format. The range can’t start before 2017-01 or exceed 12 months. Other dated reports use month in the same format.
  • Filters: Use device_type or country where supported. Audience reports support country as their only geographic filter. Some traffic reports also support subregion and state. These three geographic filters are mutually exclusive.
  • Industry: Sources, Destinations, and Visited Domains support a categories filter.
  • Sorting and pagination: List reports that support these options use order_by, direction, limit, and offset.

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:

Reports
Update schedule
Updated daily with a 4-day delay.
Updated every Thursday for the preceding week.
Get Trend Monthly, most list and audience reports
Updated between the 7th and 10th of each month.

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.

Validation error response
JSON
{
  "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.

Field
Description
meta.success
Whether the request succeeded. Failed requests return false.
meta.status_code
HTTP status code returned by the API.
meta.request_id
Unique request identifier. Include it when contacting support.
error.code
Error code. It usually matches the HTTP status code.
error.message
Description of why the request failed.
error.retryable
Whether retrying the same request may succeed. Don’t retry requests marked false.
error.details
Field validation errors. An array of objects with field 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:

HTTP status
When it happens
What to do
445, 446, 447
A request, IP address, or region is blocked by security checks.
Don’t retry. Follow the instructions in Security errors.

An 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.

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

Was this page helpful?