Run a campaign

An Enhance campaign sends visits to a website: from a search engine, from a maps listing, or directly. RankShark runs the campaign for you. The API lets you manage campaigns the same way as the panel.

All requests need an Enhance key (rsen_…). See Getting started.

Check the workspaceCopy Anchor Link

GET /api/v1/status says whether your subscription is active (campaigns only run while it is) and whether any campaign is running. Needs system:read.

curl https://panel.rankshark.io/api/v1/status \
  -H "Authorization: Bearer $RANKSHARK_ENHANCE_KEY"

List campaignsCopy Anchor Link

curl "https://panel.rankshark.io/api/v1/campaigns?offset=0&limit=100" \
  -H "Authorization: Bearer $RANKSHARK_ENHANCE_KEY"

• status: running, stopped or completed. Leave it out for all.
• search: only campaigns whose name, target or keyword contains the text.
• offset and limit page through the list (limit 1 to 1000, default 100). See Pagination.

Each campaign comes back with its name, target, keyword, whether it is running, and how many visits it has sent in total and today. Archived campaigns are listed apart, at GET /api/v1/campaigns/archived, and GET /api/v1/campaigns/overview gives the counts only.

Needs campaigns:read.

Create a campaignCopy Anchor Link

A campaign needs a name, the site to visit, how visitors find it, and how many visits to send. This one sends 500 visits that search Google for two keywords and open Harbor Bakery's site:

curl -X POST https://panel.rankshark.io/api/v1/campaigns \
  -H "Authorization: Bearer $RANKSHARK_ENHANCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "spec": {
      "campaign_name": "Harbor Bakery - organic search",
      "number_of_visitors": 500,
      "tasks": [
        {
          "mode": "search_engine",
          "search_engine": "google",
          "keywords": [
            { "value": "sourdough bakery portland", "weight": 3 },
            { "value": "harbor bakery", "weight": 1 }
          ],
          "target_address": "harborbakery.example"
        }
      ]
    }
  }'

Location, schedule, daily limits and the device mix are optional. GET /api/v1/schema/spec lists every setting with its default and allowed values.

The answer is the new campaign (201 Created). A new campaign does not start on its own. Needs campaigns:write.

Before saving, you can check a campaign with the enhance_validate_campaign MCP tool, or send it and read the 400 validation_error answer: its detail says what to fix.

To change a campaign later, send it back with PUT /api/v1/campaigns/{id}. Secret values come back as ********: leave them like that and the saved value is kept.

Where and when visits runCopy Anchor Link

• Location. Target visits to a country, region, city or ZIP code. The places on offer change over time, and the Enhance API reference lists the call that returns them.
• Schedule. Set the days and hours a campaign runs, and a daily limit. Visits run inside that window.
• Workflows. For more than a list of steps, a campaign can follow a workflow with conditions, splits, loops, delays and retries.

Start and stopCopy Anchor Link

Starting sends real visits and uses your plan. Needs campaigns:run.

curl -X POST https://panel.rankshark.io/api/v1/campaigns/start \
  -H "Authorization: Bearer $RANKSHARK_ENHANCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      "3f6c2a9e-5b1d-4c7a-9e2f-8a4b6c1d2e3f",
      "7d1e4b2a-9c3f-4e8d-a1b2-c3d4e5f6a7b8"
    ]
  }'

{
  "op": "start",
  "count": 2
}

count is how many campaigns changed. To stop every campaign at once, send { "all": true } instead of ids:

curl -X POST https://panel.rankshark.io/api/v1/campaigns/stop \
  -H "Authorization: Bearer $RANKSHARK_ENHANCE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "all": true
  }'

POST /api/v1/campaigns/restart starts campaigns again from the beginning. Start, stop and delete calls have a lower limit per key. See Rate limits.

Archive or deleteCopy Anchor Link

• Archive keeps a campaign's history and takes it off the list: POST /api/v1/campaigns/{id}/archive.
• Delete stops the campaign and erases its visits and statistics for good: DELETE /api/v1/campaigns/{id}. Needs campaigns:delete. This cannot be undone.

NextCopy Anchor Link

• Enhance reports: visits, daily totals and CSV exports.
• Enhance API reference: every endpoint with its fields.