--- name: semrush-position-tracking-report description: "Each Tuesday: your Semrush Position Tracking visibility, how it compares with the competitors in the campaign, and the keywords that moved it. Use when the user asks for this, or when it runs on a schedule." --- # Semrush position tracking report Each Tuesday: your Semrush Position Tracking visibility, how it compares with the competitors in the campaign, and the keywords that moved it. Semrush Position Tracking already compares you with the competitors you add to a campaign on the same keywords, which makes it the closest thing search has to a market share number. What it does not do is tell anyone. The visibility chart moves, and the team finds out when a competitor's blog starts appearing in every result. The agent reads the campaign through the Semrush API each week, reports your visibility and the gap to the nearest competitors, and lists the keywords that explain the change. It is the version of the report that fits in a stand-up. ## Two ways to get the data Use the API or MCP route when you have an MCP server, a CLI or an API token for the app. Otherwise, if you can drive a browser the user is signed in to (Claude in Chrome, a Playwright or Chrome DevTools MCP server), use the browser route. Say which one you used. ## Route A: API or MCP server ### What you need - A Semrush Position Tracking campaign for the site, with competitors added, and its project ID. - Semrush API access: the Projects API needs a Business subscription plus API units bought separately, with the key in `SEMRUSH_API_KEY`. The official Semrush MCP server covers keyword and domain data; check that it exposes Position Tracking before relying on it instead. If something is missing, say what and stop; do not invent numbers. ### Steps 1. **Read your rankings for both dates** (Semrush): Call the Semrush Projects API Position Tracking report, `GET https://api.semrush.com/reports/v1/projects/{project_id}/tracking/` with `action=report` and `type=tracking_position_organic`, for `url=*.example.com/*` and a `date_begin` and `date_end` 7 days apart. 2. **Add the competitors** (Semrush): Run the same report with each competitor's own `url` mask, so every domain is measured on the same keywords, location and device. 3. **Compare visibility and find movers**: Take visibility as Semrush reports it and compare the two dates for every domain. Movers changed by 3 or more positions; sort them by search volume and keep the ranking URL. 4. **Keep devices and locations apart**: If the campaign tracks mobile and desktop, or several locations, read each one separately. Averaging them hides a mobile-only drop. 5. **Post the tile**: Your visibility is the headline with 8 weeks of history. The glance shows average position and keywords in the top 3 and top 10; the card opens to the competitor table and the movers. ## Route B: the browser ### What you need - Signed in to Semrush with access to the Position Tracking project, as its owner or a user it is shared with. If something is missing, say what and stop; do not invent numbers. ### Steps Start at https://www.semrush.com/position-tracking/. The user is signed in already; never type passwords or codes, and ask if a sign-in page appears. 1. **Open the campaign**: Open `https://www.semrush.com/position-tracking/` and click the project for `example.com`. It opens on the `Landscape` tab for the campaign's default device and location. 2. **Set the two dates**: In the date picker at the top right choose today and the date 7 days earlier. Read your `Visibility` with its change, and the competitor rows underneath with their visibility and change in points. 3. **Read the summary and the buckets**: Open the `Overview` tab for Average position, then `Rankings Distribution` for the counts in the top 3 and top 10 on both dates. 4. **List the movers**: Back on `Overview`, sort the positions table by `Diff` and keep keywords that moved 3 or more positions, with position, change, volume and the ranking URL. Export when the campaign tracks more than a few hundred keywords. 5. **Check other devices and locations**: Under `Devices & Locations`, repeat for mobile or a second location when the campaign tracks them, and report each on its own. Note: Visibility in the UI is rounded to one decimal, and the positions table shows 100 rows per page. For campaigns with thousands of keywords use Export on the Overview tab and read the file. ## The report - **Visibility** this week, the change, and an 8-week trend. - **Competitors**: visibility for each domain in the campaign and the change in points. - **Top 3 and top 10** keyword counts, and average position. - **Movers**: keywords that changed by 3 or more positions, by volume, with the ranking URL. - Where you gained or lost against the closest competitor. ## Post it to Briefkin When `BRIEFKIN_TOKEN` is set, or `~/.config/briefkin/env` exists (the installer from https://briefkin.dev/docs writes it), also send the result to the user's Briefkin board as one card. Keep the `item_key` the same on every run so the card updates in place, use a new `event_id` per run, and put today's real numbers in place of the example ones. If the request fails, say so once and carry on. ```bash [ -n "${BRIEFKIN_TOKEN:-}" ] || . ~/.config/briefkin/env curl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \ -H "authorization: Bearer $BRIEFKIN_TOKEN" \ -H "content-type: application/json" \ -d @- <<'JSON' { "v": 1, "event_id": "semrush-position-tracking-report/", "item_key": "semrush-position-tracking-report", "project": "example.com", "source": "Semrush position tracking report skill", "kind": "metric", "title": "Visibility 18.6%, closing on competitor-a.com", "metric": { "label": "Visibility", "value": 18.6, "unit": "%", "better": "higher", "period_start": "", "period_end": "" }, "glance": { "type": "Grid", "props": { "columns": 3 }, "children": [ { "type": "Stat", "props": { "label": "Avg position", "value": 21.4, "delta": -3, "better": "lower" } }, { "type": "Stat", "props": { "label": "Top 3", "value": 14 } }, { "type": "Stat", "props": { "label": "Top 10", "value": 47 } } ] }, "widget": [ { "type": "Table", "props": { "columns": [ "Domain", "Visibility", "Change" ], "align": [ "left", "right", "right" ], "rows": [ [ "competitor-a.com", "21.2%", "-0.4 pts" ], [ "example.com", "18.6%", "+0.7 pts" ], [ "competitor-b.com", "12.9%", "+0.2 pts" ], [ "competitor-c.com", "9.4%", "-1.1 pts" ] ] } }, { "type": "Table", "props": { "columns": [ "Keyword", "Position", "Change", "Volume" ], "align": [ "left", "right", "right", "right" ], "rows": [ [ "online invoicing", 4, "+5", 4400 ], [ "invoice software free", 15, "-6", 3600 ], [ "invoice app", 7, "+3", 2900 ], [ "send invoice online", 2, "+3", 1600 ] ] } }, { "type": "Callout", "props": { "text": "The gap to competitor-a.com narrowed from 3.7 to 2.6 points. \"online invoicing\" moving from 9 to 4 did most of it.", "tone": "ok" } } ], "size": "md" } JSON ``` Widgets come from the Briefkin catalog (https://briefkin.dev/v1/catalog). Without a token, just give the user the report. Set `period_start` and `period_end` to the window the number covers: the tile names it from them ("Last 7 days", "Today", "This month"). For a count right now (open items, a balance), send `"period_label": ""` so no period shows; for another name, send it as `period_label` (at most 24 characters). ## Run it on a schedule Suggested: Tuesdays at 7:30 (`30 7 * * 2`). From cron, with the agent signed in on that machine: ```bash 30 7 * * 2 claude -p "Run the semrush-position-tracking-report skill" # Codex: codex exec, Gemini CLI: gemini -p, Copilot CLI: copilot -p, OpenCode: opencode run ``` Or use the agent's own scheduler (Claude Code routines, Codex automations, Claude or ChatGPT scheduled tasks): https://briefkin.dev/skills/semrush-position-tracking-report#schedule Source: https://briefkin.dev/skills/semrush-position-tracking-report