Overview

Jump to AboutAbout

The Position Tracking API v4 lets you manage tracking campaigns and monitor keyword rankings, visibility, and competitors’ performance across search engines, devices, and locations. Reports use the keywords and tracking data in your campaigns.

Use it to:

• Track organic and paid search positions and changes over time.
• Compare keyword performance across campaigns with different targets, devices, or locations.
• Analyze ranking landing pages and keyword cannibalization, where multiple URLs from the same site compete in search results.
• Compare groups of keywords using tags.

Jump to Available dataAvailable data

Campaigns support Google, Bing, and Baidu. Supported devices and metrics vary by search engine. Search volume, CPC, estimated traffic, and volume-related filters are available only for Google campaigns.

Jump to Get accessGet access

You need an SEO Business subscription and available API units. For setup instructions, refer to API access.

Authorize requests with a v4 API key.

Requests consume API units. Each method lists its unit cost and whether billing is per request or per line.

Jump to Get startedGet started

1. Find a location_id and, if needed, a language with Lookup Tracking Locations.
2. Get a campaign_id from List Project Campaigns, or use Create Campaign to set up tracking for your keywords, target, search engine, device, location, and language. For tracking_url, use a domain such as samplesite.com or a page URL such as https://samplesite.com/blog. Don’t use asterisks in tracking_url.
3. Get dates with collected data from Get Campaign Tracking Points.
4. Call a report under https://api.semrush.com/apis/v4/position-tracking/v1/seo. Most comparison reports require campaign_id, channel (ORGANIC or PAID), base_date, and comparison_date. Trend reports use date_from and date_to for the report interval. Check the endpoint for required parameters.
5. Select the report target with target_url, or omit it to use the campaign’s tracking_url. For local pack or map results without URLs, use target_business_name. Results with URLs use URL matching. Values without *, or starting with http:// or https://, match an exact URL. Supported masks:
   • *.samplesite.com/*: Root domain and subdomains.
   • www.samplesite.com/*: All paths on that host.
   • *.samplesite.com/blog/*: That subfolder on the root domain and its subdomains.
   • https://www.samplesite.com/blog/: One page.

Jump to Responses and filteringResponses and filtering

Available filters vary by endpoint. Filter report data by keyword text, tags, intent, volume, CPC, position, SERP features, or other supported criteria. Volume and CPC filters are Google-only.

In Get SEO Overview, position filters apply to target_url, or the campaign target if omitted.

• serp_features selects keywords whose search results contain a feature.
• ranks_with_serp_feature selects keywords where the target ranks in that feature.

Send one SERP-feature filter per request. If several are supplied, the first non-empty parameter wins in this order: serp_features, serp_features_exclude, ranks_with_serp_feature, not_ranks_with_serp_feature.

For supported filters, restrictions, response parameters, and examples, refer to the API reference.

Jump to Error handlingError handling

When a request fails, check the HTTP status and error response. If the response includes error.retryable, don’t retry requests marked false.

When contacting Support, include the request, response, and meta.request_id. For more help, refer to Troubleshooting.