Skip to main content

​
Prerequisites

  • A SuprKeywords account (sign up at suprkeywords.com/app).
  • At least one run (credit). Purchase run packs from the dashboard if needed.
  • Your primary domain and, optionally, competitor domains.

​
Base URL and authentication

  • Base URL: https://suprkeywords.com/app (production) or http://localhost:4605/app (local dev).
  • Authentication: Dashboard requests use Clerk session cookies. When calling the API from the browser (same origin as the app), cookies are sent automatically. For server-side or scripted calls, you must send the same cookies or use API key auth when it becomes available.

​
Step 1: Create a job

POST /api/v1/jobs creates a new keyword research job and starts the pipeline. 
curl -X POST "https://suprkeywords.com/app/api/v1/jobs" \
  -H "Content-Type: application/json" \
  -d '{
    "primaryDomain": "example.com",
    "competitorDomains": ["competitor.com"],
    "languageCode": "en",
    "locationCode": 2840
  }'
You need to include your Clerk session cookie for authenticated requests. From the dashboard, you can create jobs via the New Job form instead. Response (201): 
{
  "job": {
    "id": "uuid",
    "status": "queued",
    "createdAt": "2026-02-19T00:00:00.000Z"
  }
}

​
Step 2: Poll job status

GET /api/v1/jobs/{jobId} returns status, progress, and (when completed or failed) total keyword count. 
curl "https://suprkeywords.com/app/api/v1/jobs/YOUR_JOB_ID"
When status is completed, proceed to fetch results. When status is failed, check errorMessage.

​
Step 3: Fetch results

  • Personas: GET /api/v1/jobs/{jobId}/personas
  • Keywords: GET /api/v1/jobs/{jobId}/keywords (supports limit, offset, search, filters, sorting)
  • Clusters: GET /api/v1/jobs/{jobId}/clusters
  • Keywords in a cluster: GET /api/v1/jobs/{jobId}/clusters/{clusterId}/keywords
  • Export CSV: GET /api/v1/jobs/{jobId}/export-keywords (returns text/csv)
Example: 
curl "https://suprkeywords.com/app/api/v1/jobs/YOUR_JOB_ID/keywords?limit=10&sortBy=organicOpportunityScore&sortOrder=desc"

​
Listing languages and locations

  • GET /api/v1/languages – DataForSEO-compatible languages (e.g. for the New Job form).
  • GET /api/v1/locations – DataForSEO-compatible locations (e.g. United States = 2840).
No authentication required for these endpoints.

​
Next steps

  • See the API Reference for full endpoint details, parameters, and response schemas.
  • Use the dashboard at suprkeywords.com/app to create jobs and explore results in the UI.