Documentation

Start in the dashboard for analysis. Use the API for automation.
Same core metrics across both.

Base URL: https://sameapi.io/api/v1 • 5 minute cache TTL

2-minute quickstart

Create a free account
Run a domain lookup in the dashboard (paste or upload a list)
Export results (CSV / JSON / Excel)
If you need automation, generate an API key (X-API-Key) and use the endpoints below

Tip: Most users start in the dashboard. The API is optional.

Dashboard

Paste or upload domains, review metrics, and export results.

API

Automate lookups, batch jobs, and integrate into your workflows.

Overview

The SameApi REST API provides programmatic access to comprehensive domain analytics. Use it to retrieve traffic metrics, rankings, and audience insights for any domain.

Dashboard workflow

Paste or upload domains, review metrics, and export results in minutes.

Single Lookups

Get instant metrics for any domain with a single API call.

Batch Processing

Process millions of domains per job with enterprise-grade scalable infrastructure.

Webhooks

Receive real-time notifications when jobs complete. Integrate directly with your backend.

Authentication

All API requests require authentication using an API Key sent via the X-API-Key header. Generate API keys from your dashboard under API Access.

curl -X GET "https://sameapi.io/api/v1/lookup/facebook.com" \
  -H "X-API-Key: YOUR_API_KEY"

Token Security

• Never share tokens publicly or commit to version control
• Use environment variables to store tokens
• Rotate tokens regularly for enhanced security
• Revoke unused tokens from your dashboard

Token Limits by Plan

• Basic: 0 tokens (No API access)
• Pro: 1 token
• Ultra: 3 tokens
• Mega: 10 tokens

Interactive Playground

Test the API directly from your browser. Enter your API token and a domain to see live results.

API Playground

API Token

Domain

GET

/api/v1/lookup/facebook.com

GET

/api/v1/lookup/{domain}

Single-domain lookups always return a Job object. If the domain data is already cached, the job may be returned immediately in a completed state. Next Steps: 1) Poll GET /api/v1/jobs/{id} 2) When complete, call GET /api/v1/jobs/{id}/results 3) Display or export results

Parameters

domain

string

path

required

The domain to analyze (e.g., facebook.com)

Headers

X-API-Key

required

Your API Key

Content-Typeapplication/json

Code Examples

# Single domain lookup (Async)
# 1. Start job
curl -X GET "https://sameapi.io/api/v1/lookup/facebook.com" \
      -H "X-API-Key: YOUR_API_KEY"

# 2. Check status via simple Job ID endpoint
curl -X GET "https://sameapi.io/api/v1/jobs/job_123" \
      -H "X-API-Key: YOUR_API_KEY"

# 3. Get results
curl -X GET "https://sameapi.io/api/v1/jobs/job_123/results" \
      -H "X-API-Key: YOUR_API_KEY"

Response

Sample response (facebook.com)

Domain: facebook.com

{
  "Version": 1,
  "SiteName": "facebook.com",
  "Description": "log into facebook to start sharing and connecting with your friends, family, and people you know.",
  "TopCountryShares": [
    {
      "Country": 840,
      "CountryCode": "US",
      "Value": 0.23568593111296665
    },
    {
      "Country": 704,
      "CountryCode": "VN",
      "Value": 0.05811275204152962
    },
    {
      "Country": 608,
      "CountryCode": "PH",
      "Value": 0.055166658166604605
    },
    {
      "Country": 124,
      "CountryCode": "CA",
      "Value": 0.0384297708016332
    },
    {
      "Country": 764,
      "CountryCode": "TH",
      "Value": 0.036426558818487415
    }
  ],
  "Title": "Facebook - log in or sign up",
  "Engagments": {
    "BounceRate": "0.30400651990580924",
    "Month": "12",
    "Year": "2025",
    "PagePerVisit": "12.412364492468361",
    "Visits": "11853904289",
    "TimeOnSite": "603.2778864816132"
  },
  "EstimatedMonthlyVisits": {
    "2025-10-01": 11749095215,
    "2025-11-01": 11277047479,
    "2025-12-01": 11853904289
  },
  "GlobalRank": {
    "Rank": 3
  },
  "CountryRank": {
    "Country": 840,
    "CountryCode": "US",
    "Rank": 4
  },
  "CategoryRank": {
    "Rank": "1",
    "Category": "Computers_Electronics_and_Technology/Social_Networks_and_Online_Communities"
  },
  "GlobalCategoryRank": null,
  "IsSmall": false,
  "Policy": 0,
  "TrafficSources": {
    "Social": 0.005548611114217241,
    "Paid Referrals": 0.0019854482885637635,
    "Mail": 0.003799130926322126,
    "Referrals": 0.029816614680119227,
    "Search": 0.19982928876973552,
    "Direct": 0.759020906221042
  },
  "Category": "computers_electronics_and_technology/social_networks_and_online_communities",
  "LargeScreenshot": "https://site-images.similarcdn.com/image?url=facebook.com&t=1&s=1&h=be773d6b77aa3d59b6a671c5c27ad729b1ae77400e89776e2f749cce6b926c4b",
  "IsDataFromGa": false,
  "Countries": [
    {
      "Code": "AF",
      "UrlCode": "afghanistan",
      "Name": "Afghanistan"
    },
    {
      "Code": "AX",
      "UrlCode": "land-islands",
      "Name": "Åland Islands"
    },
    {
      "Code": "AL",
      "UrlCode": "albania",
      "Name": "Albania"
    },
    {
      "Code": "DZ",
      "UrlCode": "algeria",
      "Name": "Algeria"
    },
    {
      "Code": "AS",
      "UrlCode": "american-samoa",
      "Name": "American Samoa"
    },
    {
      "Code": "AD",
      "UrlCode": "andorra",
      "Name": "Andorra"
    },
    {
      "Code": "AO",
      "UrlCode": "angola",
      "Name": "Angola"
    },
    {
      "Code": "AI",
      "UrlCode": "anguilla",
      "Name": "Anguilla"
    },
    {
      "Code": "AQ",
      "UrlCode": "antarctica",
      "Name": "Antarctica"
    },
    {
      "Code": "AG",
      "UrlCode": "antigua-and-barbuda",
      "Name": "Antigua and Barbuda"
    },
    {
      "Code": "AR",
      "UrlCode": "argentina",
      "Name": "Argentina"
    },
    {
      "Code": "AM",
      "UrlCode": "armenia",
      "Name": "Armenia"
    },
    {
      "Code": "AW",
      "UrlCode": "aruba",
      "Name": "Aruba"
    },
    {
      "Code": "AU",
      "UrlCode": "australia",
      "Name": "Australia"
    },
    {
      "Code": "AT",
      "UrlCode": "austria",
      "Name": "Austria"
    },
    {
      "Code": "AZ",
      "UrlCode": "azerbaijan",
      "Name": "Azerbaijan"
    },
    {
      "Code": "BS",
      "UrlCode": "bahamas",
      "Name": "Bahamas"
    },
    {
      "Code": "BH",
      "UrlCode": "bahrain",
      "Name": "Bahrain"
    },
    {
      "Code": "BD",
      "UrlCode": "bangladesh",
      "Name": "Bangladesh"
    },
    {
      "Code": "BB",
      "UrlCode": "barbados",
      "Name": "Barbados"
    },
    {
      "Code": "BY",
      "UrlCode": "belarus",
      "Name": "Belarus"
    },
    {
      "Code": "BE",
      "UrlCode": "belgium",
      "Name": "Belgium"
    },
    {
      "Code": "BZ",
      "UrlCode": "belize",
      "Name": "Belize"
    },
    {
      "Code": "BJ",
      "UrlCode": "benin",
      "Name": "Benin"
    },
    {
      "Code": "BM",
      "UrlCode": "bermuda",
      "Name": "Bermuda"
    },
    {
      "Code": "BT",
      "UrlCode": "bhutan",
      "Name": "Bhutan"
    },
    {
      "Code": "BO",
      "UrlCode": "bolivia-plurinational-state-of",
      "Name": "Bolivia"
    },
    {
      "Code": "BQ",
      "UrlCode": "bonaire-sint-eustatius-and-saba",
      "Name": "Bonaire, Sint Eustatius and Saba"
    },
    {
      "Code": "BA",
      "UrlCode": "bosnia-and-herzegovina",
      "Name": "Bosnia and Herzegovina"
    },
    {
      "Code": "BW",
      "UrlCode": "botswana",
      "Name": "Botswana"
    },
    {
      "Code": "BV",
      "UrlCode": "bouvet-island",
      "Name": "Bouvet Island"
    },
    {
      "Code": "BR",
      "UrlCode": "brazil",
      "Name": "Brazil"
    },
    {
      "Code": "IO",
      "UrlCode": "british-indian-ocean-territory",
      "Name": "British Indian Ocean Territory"
    },
    {
      "Code": "BN",
      "UrlCode": "brunei-darussalam",
      "Name": "Brunei Darussalam"
    },
    {
      "Code": "BG",
      "UrlCode": "bulgaria",
      "Name": "Bulgaria"
    },
    {
      "Code": "BF",
      "UrlCode": "burkina-faso",
      "Name": "Burkina Faso"
    },
    {
      "Code": "BI",
      "UrlCode": "burundi",
      "Name": "Burundi"
    },
    {
      "Code": "CV",
      "UrlCode": "cabo-verde",
      "Name": "Cabo Verde"
    },
    {
      "Code": "KH",
      "UrlCode": "cambodia",
      "Name": "Cambodia"
    },
    {
      "Code": "CM",
      "UrlCode": "cameroon",
      "Name": "Cameroon"
    },
    {
      "Code": "CA",
      "UrlCode": "canada",
      "Name": "Canada"
    },
    {
      "Code": "KY",
      "UrlCode": "cayman-islands",
      "Name": "Cayman Islands"
    },
    {
      "Code": "CF",
      "UrlCode": "central-african-republic",
      "Name": "Central African Republic"
    },
    {
      "Code": "TD",
      "UrlCode": "chad",
      "Name": "Chad"
    },
    {
      "Code": "CL",
      "UrlCode": "chile",
      "Name": "Chile"
    },
    {
      "Code": "CN",
      "UrlCode": "china",
      "Name": "China"
    },
    {
      "Code": "CX",
      "UrlCode": "christmas-island",
      "Name": "Christmas Island"
    },
    {
      "Code": "CC",
      "UrlCode": "cocos-keeling-islands",
      "Name": "Cocos (Keeling) Islands"
    },
    {
      "Code": "CO",
      "UrlCode": "colombia",
      "Name": "Colombia"
    },
    {
      "Code": "KM",
      "UrlCode": "comoros",
      "Name": "Comoros"
    },
    {
      "Code": "CG",
      "UrlCode": "congo",
      "Name": "Congo"
    },
    {
      "Code": "CD",
      "UrlCode": "congo-the-democratic-republic-of-the",
      "Name": "Congo, the Democratic Republic of the"
    },
    {
      "Code": "CK",
      "UrlCode": "cook-islands",
      "Name": "Cook Islands"
    },
    {
      "Code": "CR",
      "UrlCode": "costa-rica",
      "Name": "Costa Rica"
    },
    {
      "Code": "CI",
      "UrlCode": "cte-divoire",
      "Name": "Côte d'Ivoire"
    },
    {
      "Code": "HR",
      "UrlCode": "croatia",
      "Name": "Croatia"
    },
    {
      "Code": "CU",
      "UrlCode": "cuba",
      "Name": "Cuba"
    },
    {
      "Code": "CW",
      "UrlCode": "curaao",
      "Name": "Curaçao"
    },
    {
      "Code": "CY",
      "UrlCode": "cyprus",
      "Name": "Cyprus"
    },
    {
      "Code": "CZ",
      "UrlCode": "czech-republic",
      "Name": "Czech Republic"
    },
    {
      "Code": "DK",
      "UrlCode": "denmark",
      "Name": "Denmark"
    },
    {
      "Code": "DJ",
      "UrlCode": "djibouti",
      "Name": "Djibouti"
    },
    {
      "Code": "DM",
      "UrlCode": "dominica",
      "Name": "Dominica"
    },
    {
      "Code": "DO",
      "UrlCode": "dominican-republic",
      "Name": "Dominican Republic"
    },
    {
      "Code": "EC",
      "UrlCode": "ecuador",
      "Name": "Ecuador"
    },
    {
      "Code": "EG",
      "UrlCode": "egypt",
      "Name": "Egypt"
    },
    {
      "Code": "SV",
      "UrlCode": "el-salvador",
      "Name": "El Salvador"
    },
    {
      "Code": "GQ",
      "UrlCode": "equatorial-guinea",
      "Name": "Equatorial Guinea"
    },
    {
      "Code": "ER",
      "UrlCode": "eritrea",
      "Name": "Eritrea"
    },
    {
      "Code": "EE",
      "UrlCode": "estonia",
      "Name": "Estonia"
    },
    {
      "Code": "ET",
      "UrlCode": "ethiopia",
      "Name": "Ethiopia"
    },
    {
      "Code": "FK",
      "UrlCode": "falkland-islands-malvinas",
      "Name": "Falkland Islands (Malvinas)"
    },
    {
      "Code": "FO",
      "UrlCode": "faroe-islands",
      "Name": "Faroe Islands"
    },
    {
      "Code": "FJ",
      "UrlCode": "fiji",
      "Name": "Fiji"
    },
    {
      "Code": "FI",
      "UrlCode": "finland",
      "Name": "Finland"
    },
    {
      "Code": "FR",
      "UrlCode": "france",
      "Name": "France"
    },
    {
      "Code": "GF",
      "UrlCode": "french-guiana",
      "Name": "French Guiana"
    },
    {
      "Code": "PF",
      "UrlCode": "french-polynesia",
      "Name": "French Polynesia"
    },
    {
      "Code": "TF",
      "UrlCode": "french-southern-territories",
      "Name": "French Southern Territories"
    },
    {
      "Code": "GA",
      "UrlCode": "gabon",
      "Name": "Gabon"
    },
    {
      "Code": "GM",
      "UrlCode": "gambia",
      "Name": "Gambia"
    },
    {
      "Code": "GE",
      "UrlCode": "georgia",
      "Name": "Georgia"
    },
    {
      "Code": "DE",
      "UrlCode": "germany",
      "Name": "Germany"
    },
    {
      "Code": "GH",
      "UrlCode": "ghana",
      "Name": "Ghana"
    },
    {
      "Code": "GI",
      "UrlCode": "gibraltar",
      "Name": "Gibraltar"
    },
    {
      "Code": "GR",
      "UrlCode": "greece",
      "Name": "Greece"
    },
    {
      "Code": "GL",
      "UrlCode": "greenland",
      "Name": "Greenland"
    },
    {
      "Code": "GD",
      "UrlCode": "grenada",
      "Name": "Grenada"
    },
    {
      "Code": "GP",
      "UrlCode": "guadeloupe",
      "Name": "Guadeloupe"
    },
    {
      "Code": "GU",
      "UrlCode": "guam",
      "Name": "Guam"
    },
    {
      "Code": "GT",
      "UrlCode": "guatemala",
      "Name": "Guatemala"
    },
    {
      "Code": "GG",
      "UrlCode": "guernsey",
      "Name": "Guernsey"
    },
    {
      "Code": "GN",
      "UrlCode": "guinea",
      "Name": "Guinea"
    },
    {
      "Code": "GW",
      "UrlCode": "guinea-bissau",
      "Name": "Guinea-Bissau"
    },
    {
      "Code": "GY",
      "UrlCode": "guyana",
      "Name": "Guyana"
    },
    {
      "Code": "HT",
      "UrlCode": "haiti",
      "Name": "Haiti"
    },
    {
      "Code": "HM",
      "UrlCode": "heard-island-and-mcdonald-islands",
      "Name": "Heard Island and McDonald Islands"
    },
    {
      "Code": "VA",
      "UrlCode": "holy-see-vatican-city-state",
      "Name": "Holy See (Vatican City State)"
    },
    {
      "Code": "HN",
      "UrlCode": "honduras",
      "Name": "Honduras"
    },
    {
      "Code": "HK",
      "UrlCode": "hong-kong",
      "Name": "Hong Kong"
    },
    {
      "Code": "HU",
      "UrlCode": "hungary",
      "Name": "Hungary"
    },
    {
      "Code": "IS",
      "UrlCode": "iceland",
      "Name": "Iceland"
    },
    {
      "Code": "IN",
      "UrlCode": "india",
      "Name": "India"
    },
    {
      "Code": "ID",
      "UrlCode": "indonesia",
      "Name": "Indonesia"
    },
    {
      "Code": "IR",
      "UrlCode": "iran-islamic-republic-of",
      "Name": "Iran"
    },
    {
      "Code": "IQ",
      "UrlCode": "iraq",
      "Name": "Iraq"
    },
    {
      "Code": "IE",
      "UrlCode": "ireland",
      "Name": "Ireland"
    },
    {
      "Code": "IM",
      "UrlCode": "isle-of-man",
      "Name": "Isle of Man"
    },
    {
      "Code": "IL",
      "UrlCode": "israel",
      "Name": "Israel"
    },
    {
      "Code": "IT",
      "UrlCode": "italy",
      "Name": "Italy"
    },
    {
      "Code": "JM",
      "UrlCode": "jamaica",
      "Name": "Jamaica"
    },
    {
      "Code": "JP",
      "UrlCode": "japan",
      "Name": "Japan"
    },
    {
      "Code": "JE",
      "UrlCode": "jersey",
      "Name": "Jersey"
    },
    {
      "Code": "JO",
      "UrlCode": "jordan",
      "Name": "Jordan"
    },
    {
      "Code": "KZ",
      "UrlCode": "kazakhstan",
      "Name": "Kazakhstan"
    },
    {
      "Code": "KE",
      "UrlCode": "kenya",
      "Name": "Kenya"
    },
    {
      "Code": "KI",
      "UrlCode": "kiribati",
      "Name": "Kiribati"
    },
    {
      "Code": "KP",
      "UrlCode": "korea-democratic-peoples-republic-of",
      "Name": "Korea, Democratic People's Republic of"
    },
    {
      "Code": "KR",
      "UrlCode": "korea-republic-of",
      "Name": "Korea, Republic of"
    },
    {
      "Code": "KW",
      "UrlCode": "kuwait",
      "Name": "Kuwait"
    },
    {
      "Code": "KG",
      "UrlCode": "kyrgyzstan",
      "Name": "Kyrgyzstan"
    },
    {
      "Code": "LA",
      "UrlCode": "lao-peoples-democratic-republic",
      "Name": "Lao People's Democratic Republic"
    },
    {
      "Code": "LV",
      "UrlCode": "latvia",
      "Name": "Latvia"
    },
    {
      "Code": "LB",
      "UrlCode": "lebanon",
      "Name": "Lebanon"
    },
    {
      "Code": "LS",
      "UrlCode": "lesotho",
      "Name": "Lesotho"
    },
    {
      "Code": "LR",
      "UrlCode": "liberia",
      "Name": "Liberia"
    },
    {
      "Code": "LY",
      "UrlCode": "libya",
      "Name": "Libya"
    },
    {
      "Code": "LI",
      "UrlCode": "liechtenstein",
      "Name": "Liechtenstein"
    },
    {
      "Code": "LT",
      "UrlCode": "lithuania",
      "Name": "Lithuania"
    },
    {
      "Code": "LU",
      "UrlCode": "luxembourg",
      "Name": "Luxembourg"
    },
    {
      "Code": "MO",
      "UrlCode": "macao",
      "Name": "Macao"
    },
    {
      "Code": "MK",
      "UrlCode": "macedonia-the-former-yugoslav-republic-of",
      "Name": "Macedonia (FYROM)"
    },
    {
      "Code": "MG",
      "UrlCode": "madagascar",
      "Name": "Madagascar"
    },
    {
      "Code": "MW",
      "UrlCode": "malawi",
      "Name": "Malawi"
    },
    {
      "Code": "MY",
      "UrlCode": "malaysia",
      "Name": "Malaysia"
    },
    {
      "Code": "MV",
      "UrlCode": "maldives",
      "Name": "Maldives"
    },
    {
      "Code": "ML",
      "UrlCode": "mali",
      "Name": "Mali"
    },
    {
      "Code": "MT",
      "UrlCode": "malta",
      "Name": "Malta"
    },
    {
      "Code": "MH",
      "UrlCode": "marshall-islands",
      "Name": "Marshall Islands"
    },
    {
      "Code": "MQ",
      "UrlCode": "martinique",
      "Name": "Martinique"
    },
    {
      "Code": "MR",
      "UrlCode": "mauritania",
      "Name": "Mauritania"
    },
    {
      "Code": "MU",
      "UrlCode": "mauritius",
      "Name": "Mauritius"
    },
    {
      "Code": "YT",
      "UrlCode": "mayotte",
      "Name": "Mayotte"
    },
    {
      "Code": "MX",
      "UrlCode": "mexico",
      "Name": "Mexico"
    },
    {
      "Code": "FM",
      "UrlCode": "micronesia-federated-states-of",
      "Name": "Micronesia, Federated States of"
    },
    {
      "Code": "MD",
      "UrlCode": "moldova-republic-of",
      "Name": "Moldova"
    },
    {
      "Code": "MC",
      "UrlCode": "monaco",
      "Name": "Monaco"
    },
    {
      "Code": "MN",
      "UrlCode": "mongolia",
      "Name": "Mongolia"
    },
    {
      "Code": "ME",
      "UrlCode": "montenegro",
      "Name": "Montenegro"
    },
    {
      "Code": "MS",
      "UrlCode": "montserrat",
      "Name": "Montserrat"
    },
    {
      "Code": "MA",
      "UrlCode": "morocco",
      "Name": "Morocco"
    },
    {
      "Code": "MZ",
      "UrlCode": "mozambique",
      "Name": "Mozambique"
    },
    {
      "Code": "MM",
      "UrlCode": "myanmar",
      "Name": "Myanmar"
    },
    {
      "Code": "NA",
      "UrlCode": "namibia",
      "Name": "Namibia"
    },
    {
      "Code": "NR",
      "UrlCode": "nauru",
      "Name": "Nauru"
    },
    {
      "Code": "NP",
      "UrlCode": "nepal",
      "Name": "Nepal"
    },
    {
      "Code": "NL",
      "UrlCode": "netherlands",
      "Name": "Netherlands"
    },
    {
      "Code": "AN",
      "UrlCode": "netherlands-antilles",
      "Name": "Netherlands Antilles"
    },
    {
      "Code": "NC",
      "UrlCode": "new-caledonia",
      "Name": "New Caledonia"
    },
    {
      "Code": "NZ",
      "UrlCode": "new-zealand",
      "Name": "New Zealand"
    },
    {
      "Code": "NI",
      "UrlCode": "nicaragua",
      "Name": "Nicaragua"
    },
    {
      "Code": "NE",
      "UrlCode": "niger",
      "Name": "Niger"
    },
    {
      "Code": "NG",
      "UrlCode": "nigeria",
      "Name": "Nigeria"
    },
    {
      "Code": "NU",
      "UrlCode": "niue",
      "Name": "Niue"
    },
    {
      "Code": "AP",
      "UrlCode": "non-spec-asia-pas-location",
      "Name": "Non-spec Asia Pas Location"
    },
    {
      "Code": "NF",
      "UrlCode": "norfolk-island",
      "Name": "Norfolk Island"
    },
    {
      "Code": "MP",
      "UrlCode": "northern-mariana-islands",
      "Name": "Northern Mariana Islands"
    },
    {
      "Code": "NO",
      "UrlCode": "norway",
      "Name": "Norway"
    },
    {
      "Code": "OM",
      "UrlCode": "oman",
      "Name": "Oman"
    },
    {
      "Code": "PK",
      "UrlCode": "pakistan",
      "Name": "Pakistan"
    },
    {
      "Code": "PW",
      "UrlCode": "palau",
      "Name": "Palau"
    },
    {
      "Code": "PS",
      "UrlCode": "palestine-state-of",
      "Name": "Palestine"
    },
    {
      "Code": "PA",
      "UrlCode": "panama",
      "Name": "Panama"
    },
    {
      "Code": "PG",
      "UrlCode": "papua-new-guinea",
      "Name": "Papua New Guinea"
    },
    {
      "Code": "PY",
      "UrlCode": "paraguay",
      "Name": "Paraguay"
    },
    {
      "Code": "PE",
      "UrlCode": "peru",
      "Name": "Peru"
    },
    {
      "Code": "PH",
      "UrlCode": "philippines",
      "Name": "Philippines"
    },
    {
      "Code": "PN",
      "UrlCode": "pitcairn",
      "Name": "Pitcairn"
    },
    {
      "Code": "PL",
      "UrlCode": "poland",
      "Name": "Poland"
    },
    {
      "Code": "PT",
      "UrlCode": "portugal",
      "Name": "Portugal"
    },
    {
      "Code": "PR",
      "UrlCode": "puerto-rico",
      "Name": "Puerto Rico"
    },
    {
      "Code": "QA",
      "UrlCode": "qatar",
      "Name": "Qatar"
    },
    {
      "Code": "RE",
      "UrlCode": "runion",
      "Name": "Réunion"
    },
    {
      "Code": "RO",
      "UrlCode": "romania",
      "Name": "Romania"
    },
    {
      "Code": "RU",
      "UrlCode": "russian-federation",
      "Name": "Russia"
    },
    {
      "Code": "RW",
      "UrlCode": "rwanda",
      "Name": "Rwanda"
    },
    {
      "Code": "BL",
      "UrlCode": "saint-barthlemy",
      "Name": "Saint Barthélemy"
    },
    {
      "Code": "SH",
      "UrlCode": "saint-helena-ascension-and-tristan-da-cunha",
      "Name": "Saint Helena, Ascension and Tristan da Cunha"
    },
    {
      "Code": "KN",
      "UrlCode": "saint-kitts-and-nevis",
      "Name": "Saint Kitts and Nevis"
    },
    {
      "Code": "LC",
      "UrlCode": "saint-lucia",
      "Name": "Saint Lucia"
    },
    {
      "Code": "MF",
      "UrlCode": "saint-martin-french-part",
      "Name": "Saint Martin (French part)"
    },
    {
      "Code": "PM",
      "UrlCode": "saint-pierre-and-miquelon",
      "Name": "Saint Pierre and Miquelon"
    },
    {
      "Code": "VC",
      "UrlCode": "saint-vincent-and-the-grenadines",
      "Name": "Saint Vincent and the Grenadines"
    },
    {
      "Code": "WS",
      "UrlCode": "samoa",
      "Name": "Samoa"
    },
    {
      "Code": "SM",
      "UrlCode": "san-marino",
      "Name": "San Marino"
    },
    {
      "Code": "ST",
      "UrlCode": "sao-tome-and-principe",
      "Name": "Sao Tome and Principe"
    },
    {
      "Code": "SA",
      "UrlCode": "saudi-arabia",
      "Name": "Saudi Arabia"
    },
    {
      "Code": "SN",
      "UrlCode": "senegal",
      "Name": "Senegal"
    },
    {
      "Code": "RS",
      "UrlCode": "serbia",
      "Name": "Serbia"
    },
    {
      "Code": "CS",
      "UrlCode": "serbia-and-montenegro",
      "Name": "SERBIA AND MONTENEGRO"
    },
    {
      "Code": "SC",
      "UrlCode": "seychelles",
      "Name": "Seychelles"
    },
    {
      "Code": "SL",
      "UrlCode": "sierra-leone",
      "Name": "Sierra Leone"
    },
    {
      "Code": "SG",
      "UrlCode": "singapore",
      "Name": "Singapore"
    },
    {
      "Code": "SX",
      "UrlCode": "sint-maarten-dutch-part",
      "Name": "Sint Maarten (Dutch part)"
    },
    {
      "Code": "SK",
      "UrlCode": "slovakia",
      "Name": "Slovakia"
    },
    {
      "Code": "SI",
      "UrlCode": "slovenia",
      "Name": "Slovenia"
    },
    {
      "Code": "SB",
      "UrlCode": "solomon-islands",
      "Name": "Solomon Islands"
    },
    {
      "Code": "SO",
      "UrlCode": "somalia",
      "Name": "Somalia"
    },
    {
      "Code": "ZA",
      "UrlCode": "south-africa",
      "Name": "South Africa"
    },
    {
      "Code": "GS",
      "UrlCode": "south-georgia-and-the-south-sandwich-islands",
      "Name": "South Georgia and the South Sandwich Islands"
    },
    {
      "Code": "SS",
      "UrlCode": "south-sudan",
      "Name": "South Sudan"
    },
    {
      "Code": "ES",
      "UrlCode": "spain",
      "Name": "Spain"
    },
    {
      "Code": "LK",
      "UrlCode": "sri-lanka",
      "Name": "Sri Lanka"
    },
    {
      "Code": "SD",
      "UrlCode": "sudan",
      "Name": "Sudan"
    },
    {
      "Code": "SR",
      "UrlCode": "suriname",
      "Name": "Suriname"
    },
    {
      "Code": "SJ",
      "UrlCode": "svalbard-and-jan-mayen",
      "Name": "Svalbard and Jan Mayen"
    },
    {
      "Code": "SZ",
      "UrlCode": "swaziland",
      "Name": "Swaziland"
    },
    {
      "Code": "SE",
      "UrlCode": "sweden",
      "Name": "Sweden"
    },
    {
      "Code": "CH",
      "UrlCode": "switzerland",
      "Name": "Switzerland"
    },
    {
      "Code": "SY",
      "UrlCode": "syrian-arab-republic",
      "Name": "Syrian Arab Republic"
    },
    {
      "Code": "TW",
      "UrlCode": "taiwan",
      "Name": "Taiwan"
    },
    {
      "Code": "TJ",
      "UrlCode": "tajikistan",
      "Name": "Tajikistan"
    },
    {
      "Code": "TZ",
      "UrlCode": "tanzania-united-republic-of",
      "Name": "Tanzania, United Republic of"
    },
    {
      "Code": "TH",
      "UrlCode": "thailand",
      "Name": "Thailand"
    },
    {
      "Code": "TL",
      "UrlCode": "timor-leste",
      "Name": "Timor-Leste"
    },
    {
      "Code": "TG",
      "UrlCode": "togo",
      "Name": "Togo"
    },
    {
      "Code": "TK",
      "UrlCode": "tokelau",
      "Name": "Tokelau"
    },
    {
      "Code": "TO",
      "UrlCode": "tonga",
      "Name": "Tonga"
    },
    {
      "Code": "TT",
      "UrlCode": "trinidad-and-tobago",
      "Name": "Trinidad and Tobago"
    },
    {
      "Code": "TN",
      "UrlCode": "tunisia",
      "Name": "Tunisia"
    },
    {
      "Code": "TR",
      "UrlCode": "turkey",
      "Name": "Turkey"
    },
    {
      "Code": "TM",
      "UrlCode": "turkmenistan",
      "Name": "Turkmenistan"
    },
    {
      "Code": "TC",
      "UrlCode": "turks-and-caicos-islands",
      "Name": "Turks and Caicos Islands"
    },
    {
      "Code": "TV",
      "UrlCode": "tuvalu",
      "Name": "Tuvalu"
    },
    {
      "Code": "UG",
      "UrlCode": "uganda",
      "Name": "Uganda"
    },
    {
      "Code": "UA",
      "UrlCode": "ukraine",
      "Name": "Ukraine"
    },
    {
      "Code": "AE",
      "UrlCode": "united-arab-emirates",
      "Name": "United Arab Emirates"
    },
    {
      "Code": "GB",
      "UrlCode": "united-kingdom",
      "Name": "United Kingdom"
    },
    {
      "Code": "US",
      "UrlCode": "united-states",
      "Name": "United States"
    },
    {
      "Code": "UM",
      "UrlCode": "united-states-minor-outlying-islands",
      "Name": "United States Minor Outlying Islands"
    },
    {
      "Code": "UY",
      "UrlCode": "uruguay",
      "Name": "Uruguay"
    },
    {
      "Code": "UZ",
      "UrlCode": "uzbekistan",
      "Name": "Uzbekistan"
    },
    {
      "Code": "VU",
      "UrlCode": "vanuatu",
      "Name": "Vanuatu"
    },
    {
      "Code": "VE",
      "UrlCode": "venezuela-bolivarian-republic-of",
      "Name": "Venezuela"
    },
    {
      "Code": "VN",
      "UrlCode": "vietnam",
      "Name": "Vietnam"
    },
    {
      "Code": "VG",
      "UrlCode": "virgin-islands-british",
      "Name": "Virgin Islands, British"
    },
    {
      "Code": "VI",
      "UrlCode": "virgin-islands-us",
      "Name": "Virgin Islands, U.S."
    },
    {
      "Code": "WF",
      "UrlCode": "wallis-and-futuna",
      "Name": "Wallis and Futuna"
    },
    {
      "Code": "EH",
      "UrlCode": "western-sahara",
      "Name": "Western Sahara"
    },
    {
      "Code": "YE",
      "UrlCode": "yemen",
      "Name": "Yemen"
    },
    {
      "Code": "ZM",
      "UrlCode": "zambia",
      "Name": "Zambia"
    },
    {
      "Code": "ZW",
      "UrlCode": "zimbabwe",
      "Name": "Zimbabwe"
    }
  ],
  "Competitors": {
    "TopSimilarityCompetitors": []
  },
  "Notification": {
    "Content": null
  },
  "TopKeywords": [
    {
      "Name": "facebook",
      "EstimatedValue": 124474520,
      "Volume": 111498150,
      "Cpc": 0.97
    },
    {
      "Name": "fb",
      "EstimatedValue": 21213430,
      "Volume": 20168620,
      "Cpc": 0.45
    },
    {
      "Name": "facebook login",
      "EstimatedValue": 5281970,
      "Volume": 4130490,
      "Cpc": 2.15
    },
    {
      "Name": "facebook marketplace",
      "EstimatedValue": 5110710,
      "Volume": 4814750,
      "Cpc": 1.66
    },
    {
      "Name": "face",
      "EstimatedValue": 2163100,
      "Volume": 2893360,
      "Cpc": 0.62
    }
  ],
  "SnapshotDate": "2025-12-01T00:00:00+00:00"
}

This is a real example payload shown in full.

POST

/api/v1/jobs

Create a new job. If 'domains' are provided, processing starts immediately (unless over limits). If 'domains' is empty, a Draft Job is created for Chunked Uploads. **Note**: Use this for the Chunked Upload Workflow (1. Create Draft, 2. Upload Chunks, 3. Finalize).

Parameters

name

string

body

Optional name for the job

domains

string[]

body

Array of domains (optional for Draft jobs)

webhook_url

string

body

URL to receive completion webhook

columns

string[]

body

Specific columns to include in results

Headers

X-API-Key

required

Your API Key

Content-Type

required

application/json

Code Examples

# 1. Create Draft Job (Chunked Workflow)
curl -X POST "https://sameapi.io/api/v1/jobs" \
      -H "X-API-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "name": "Large Job" }'

Request Body

{
  "name": "Large Analysis Job",
  "domains": [] 
}

Response

{
  "id": "5dc22f15-a637-41ce-8a77-a629bc105b70",
  "status": "draft",
  "total_domains": 0,
  "created_at": "2026-01-23T16:41:03.219001Z"
}

POST

/api/v1/jobs/{id}/domains

Upload a chunk of domains to a Draft Job. Max 10,000 domains per request.

Parameters

id

string

path

required

The Job ID

domains

string[]

body

required

Array of domains to add

Headers

X-API-Key

required

Your API Key

Content-Type

required

application/json

Code Examples

# 2. Upload Domains Chunk
curl -X POST "https://sameapi.io/api/v1/jobs/job_123/domains" \
      -H "X-API-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "domains": ["example1.com", "example2.com"] }'

Request Body

{
  "domains": ["example1.com", "example2.com", "..."]
}

Response

{
  "id": "5dc22f15-...",
  "status": "draft",
  "total_domains": 10000,
  "warning_message": null
}

POST

/api/v1/jobs/{id}/finalize

Finalize a Draft Job and start processing. Deducts credits from quota.

Parameters

id

string

path

required

The Job ID

Headers

X-API-Key

required

Your API Key

Code Examples

# 3. Finalize Job (Start Processing)
curl -X POST "https://sameapi.io/api/v1/jobs/job_123/finalize" \
      -H "X-API-Key: YOUR_API_KEY"

Response

{
  "id": "5dc22f15-...",
  "status": "processing",
  "total_domains": 50000,
  "started_at": "2026-01-26T10:00:00Z"
}

POST

/api/v1/lookup/batch

Simplified batch lookup. Equivalent to creating a job with domains immediately. Max 10,000 domains.

Parameters

domains

string[]

body

required

Array of domains (max 10,000)

name

string

body

Optional name

Headers

X-API-Key

required

Your API Key

Code Examples

# Quick Batch (Small jobs < 10k)
curl -X POST "https://sameapi.io/api/v1/lookup/batch" \
      -H "X-API-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
    "domains": ["google.com", "facebook.com"],
    "name": "Quick Batch"
  }'

Request Body

{
  "domains": ["google.com", "facebook.com"],
  "name": "Quick Batch"
}

Response

{
  "id": "job_123...",
  "status": "pending",
  "total_domains": 2
}

Large Jobs (Chunked Upload)

For jobs exceeding 10,000 domains (up to 1,000,000 depending on your plan), you must use the chunked upload workflow. This allows you to create a single job and upload domains in multiple batches.

Workflow

Create Draft Job: Call POST /api/v1/jobs with metadata (name, webhook) but without domains.
Response: Job ID with status draft.
Upload Chunks: Call POST /api/v1/jobs/{id}/domains multiple times.
Max 10,000 domains per request. Safe to retry (idempotent via deduplication).
Finalize: Call POST /api/v1/jobs/{id}/finalize to start processing.
Validates quota and transitions job to pending.

Note: Uploading domains does not consume credits. Credits are only deducted when you call finalize and the job enters the processing state.

Code Example (Python)

import requests

API_KEY = "YOUR_KEY"
headers = {"X-API-Key": API_KEY}
BASE = "https://sameapi.io/api/v1"

# 1. Create Draft
job = requests.post(f"{BASE}/jobs", json={"name": "Big Job"}, headers=headers).json()
job_id = job["id"]

# 2. Upload Chunks (assuming list of 21,000 domains)
domains = ["d1.com", "d2.com", ...] # 21k domains
chunk_size = 10000

for i in range(0, len(domains), chunk_size):
    chunk = domains[i:i + chunk_size]
    requests.post(f"{BASE}/jobs/{job_id}/domains", json={"domains": chunk}, headers=headers)
    print(f"Uploaded chunk {i//chunk_size + 1}")

# 3. Finalize
requests.post(f"{BASE}/jobs/{job_id}/finalize", headers=headers)
print("Job started!")

Job Lifecycle & Cancellation

Long-running jobs transition through specific states. You can monitor these states via the status endpoint.

Job States

draft: Job created but waiting for domain uploads/finalization. (Credits not consumed)
pending: Job accepted and queued for processing. (Refundable)
retry_scheduled: Temporary failure occurred; job is queued for retry. (Refundable)
processing: Worker has picked up the job. Execution is in progress. (Non-refundable)
completed: All domains processed associated with the job.
failed: Job failed due to system error or partial failure.
failed_final: Job failed and exhausted all retries.
canceled: User initiated cancellation.

Cancellation Policy

When a job is canceled, domains in pending or retry_scheduled states are not processed and their credits are automatically refunded to your quota. Domains that have already entered the processing state or completed are not refundable.

GET

/api/v1/jobs/{id}

Get the current status and progress of a job

Parameters

id

string

path

required

The unique job identifier

Headers

X-API-Key

required

Your API Key

Code Examples

# Check job status
curl -X GET "https://sameapi.io/api/v1/jobs/job_123" \
      -H "X-API-Key: YOUR_API_KEY"

Response

{
  "id": "5dc22f15-a637-41ce-8a77-a629bc105b70",
  "status": "completed",
  "total_domains": 3,
  "processed_domains": 3,
  "successful_domains": 3,
  "failed_domains": 0,
  "created_at": "2026-01-23T16:41:03.219001Z",
  "completed_at": "2026-01-23T16:45:00Z"
}

GET

/api/v1/jobs/{id}/results

Get paginated results from a completed job. Supports filtering and export.

Incremental Results

Results are available in real-time as they are processed. You do **not** need to wait for the job to reach `completed` status to start fetching data. Use `skip` and `limit` to poll for new results while the job is in `processing` state.

Parameters

id

string

path

required

The unique job identifier

page

integer

query

Page number (default: 1)

per_page

integer

query

Results per page (default: 100, max: 1000)

success_only

boolean

query

If true, returns only successful lookups

filters

string

query

JSON string of filters (e.g. `[{"field":"global_rank","operator":"lt","value":1000}]`)

format

string

query

Response format: 'json' (default) or 'csv'

Headers

X-API-Key

required

Your API Key

Code Examples

# Get job results (Filtered)
curl -X GET "https://sameapi.io/api/v1/jobs/job_123/results?success_only=true" \
      -H "X-API-Key: YOUR_API_KEY"

Response

{
        "items": [
          {
            "domain": "google.com",
            "success": true,
            "rankings": { "global": 1, "country": 1 },
            "traffic": { "visits": 89000000000 },
            "sources": { "direct": 0.5, "search": 0.3 }
          }
        ],
        "total": 1
      }

POST

/api/v1/jobs/{id}/{action}

Control job execution state. Actions: `pause`, `resume`, `cancel`, `retry-failed`.

Actions

- **cancel**: Stops processing. Refundable domains (pending) are credited back. - **pause**: Temporarily stops processing. - **resume**: Resumes a paused job. - **retry-failed**: Retries domains that failed with temporary errors.

Parameters

id

string

path

required

Job ID

action

string

path

required

One of: cancel, pause, resume, retry-failed

Headers

X-API-Key

required

Your API Key

Code Examples

# Cancel Job
curl -X POST "https://sameapi.io/api/v1/jobs/job_123/cancel" \
      -H "X-API-Key: YOUR_API_KEY"

Response

{
  "id": "job_123...",
  "status": "canceled" 
}

GET

/api/v1/usage

Get your current API usage statistics and quota

Headers

X-API-Key

required

Your API Key

Code Examples

# Get usage statistics
curl -X GET "https://sameapi.io/api/v1/usage" \
      -H "X-API-Key: YOUR_API_KEY"

Response

{
        "plan": "mega",
        "quota": {
          "monthly_limit": 1000000,
          "used": 613066,
          "remaining": 386934
        },
        "rate_limits": {
          "requests_per_second": 75,
          "concurrent_jobs": 30,
          "max_inflight": 500
        }
      }

Billing & Quota Semantics

It is important to distinguish between historical request counters and actual credit consumption, especially when using cancellations.

Metric	Description
requests_total	Total API calls made. This counter does not decrease when a job is canceled.
credits_consumed	Actual billing units used. Increases when processing starts.
credits_refunded	Credits returned to your quota after cancellation or system failure.
remaining_quota	Available credits: `(limit + overage) - (consumed - refunded)`.

Note: Historical request counters do not decrease when a job is canceled. Rely on remaining_quota for billing logic.

Webhooks

Configure webhooks to receive real-time notifications when events occur. All webhook payloads include an HMAC-SHA256 signature for verification.

Signature Verification

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

job.completed

Triggered when a batch job finishes processing (success or partial failure)

{
  "event": "job.completed",
    "job_id": "job_a1b2c3d4e5f6",
      "status": "completed",
        "total_domains": 1000,
          "successful_domains": 985,
            "failed_domains": 15,
              "created_at": "2024-01-15T10:30:00Z",
                "completed_at": "2024-01-15T10:35:00Z"
}

job.failed

Triggered when a batch job fails completely (e.g. system error)

{
  "event": "job.failed",
    "job_id": "job_a1b2c3d4e5f6",
      "status": "failed",
        "error": "Internal processing error",
          "created_at": "2024-01-15T10:30:00Z",
            "completed_at": "2024-01-15T10:30:05Z"
}

Guarantees & Consistency

Job cancellation is idempotent: Calling cancel multiple times is safe and has no side effects.
No double billing: Domains are strictly deducted once upon processing.
Canceled domains are never processed: Once confirmed canceled, a domain will not trigger a worker.
Atomic Refunds: Refunds for canceled/failed items are applied automatically and atomically.
Concurrency Safe: All operations are safe under heavy concurrency and automatic retries.

Error Codes

The API uses standard HTTP status codes and returns typed error responses.

Code	Name	Description
400	Bad Request	Invalid request parameters or malformed JSON
401	Unauthorized	Missing or invalid API token
403	Forbidden	Quota exceeded or insufficient permissions
404	Not Found	Domain, job, or resource not found
429	Too Many Requests	Rate limit exceeded, retry after delay
500	Internal Error	Server error, please retry with exponential backoff
503	Service Unavailable	Service temporarily unavailable, retry later

Error Response Format

{
  "success": false,
  "error": "quota_exceeded",
  "message": "Monthly quota exceeded. Upgrade plan or enable overage.",
  "details": {
    "used": 10000,
    "limit": 10000,
    "overage_available": true
  }
}

Rate Limits

Rate limits are applied per API token and per second, and vary by subscription plan.

Plan	Requests/sec	Monthly Quota	Overage
Basic	No API access	200	Not available
Pro	10	10,000	$0.003/request
Ultra	30	50,000	$0.002/request
Mega	75	1,000,000	$0.001/request

Rate Limit Headers

All API responses include rate limit information in headers:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 5
X-RateLimit-Reset: 1705312800
Retry-After: 1  # Only present when rate limited

Ready to get started?

Start in the dashboard in minutes. Use the API when you need automation.

Get API Key View Pricing