> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surnex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Domain keyword analysis

> Get keywords that a domain organically ranks for. Returns up to 1000 keywords with metrics via DataForSEO Labs.



## OpenAPI

````yaml https://api.surnex.io/openapi.json post /v1/keywords/domain
openapi: 3.1.0
info:
  title: Surnex API
  description: |-
    Surnex SEO Platform API — api.surnex.io

    Provides the complete backend for the Surnex SEO dashboard including:
    - Multi-tenant organization management
    - Project tracking (domains)
    - Keyword rank tracking (Phase 1+)
    - Backlink analysis (Phase 3+)
    - Site auditing (Phase 4+)
    - Stripe billing integration
    - MCP endpoint for AI agents at /mcp
  version: 0.1.0
servers: []
security: []
paths:
  /v1/keywords/domain:
    post:
      tags:
        - Keywords
      summary: Domain keyword analysis
      description: >-
        Get keywords that a domain organically ranks for. Returns up to 1000
        keywords with metrics via DataForSEO Labs.
      operationId: get_domain_keywords_v1_keywords_domain_post
      parameters:
        - name: project_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: uuid
              - type: 'null'
            description: Project ID for search history
            title: Project Id
          description: Project ID for search history
        - name: X-API-Key
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainKeywordsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIResponse_list_KeywordMetrics__'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    DomainKeywordsRequest:
      properties:
        domain:
          type: string
          maxLength: 255
          minLength: 1
          title: Domain
          description: >-
            Domain to analyze (e.g., 'example.com'). Protocol stripped
            automatically.
        limit:
          type: integer
          maximum: 1000
          minimum: 1
          title: Limit
          description: Maximum number of keywords to return.
          default: 100
        location_code:
          type: integer
          title: Location Code
          description: DataForSEO location code (e.g. 2840 = United States).
        language_code:
          type: string
          maxLength: 10
          title: Language Code
          description: Language code (e.g., 'en', 'de', 'fr').
      type: object
      required:
        - domain
        - location_code
        - language_code
      title: DomainKeywordsRequest
      description: Request body for fetching keywords that a domain ranks for.
    APIResponse_list_KeywordMetrics__:
      properties:
        success:
          type: boolean
          title: Success
          default: true
        data:
          anyOf:
            - items:
                $ref: '#/components/schemas/KeywordMetrics'
              type: array
            - type: 'null'
          title: Data
      type: object
      title: APIResponse[list[KeywordMetrics]]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    KeywordMetrics:
      properties:
        keyword:
          type: string
          title: Keyword
          description: The researched keyword.
        search_volume:
          anyOf:
            - type: integer
            - type: 'null'
          title: Search Volume
          description: Average monthly search volume over the past 12 months.
        keyword_difficulty:
          anyOf:
            - type: number
            - type: 'null'
          title: Keyword Difficulty
          description: Keyword difficulty score (0–100). Higher = harder to rank.
        cpc:
          anyOf:
            - type: number
            - type: 'null'
          title: Cpc
          description: Average cost-per-click in USD for Google Ads.
        competition:
          anyOf:
            - type: number
            - type: 'null'
          title: Competition
          description: Google Ads competition level (0.0–1.0).
        competition_index:
          anyOf:
            - type: integer
            - type: 'null'
          title: Competition Index
          description: Numeric competition score (0–100).
        competition_level:
          anyOf:
            - type: string
            - type: 'null'
          title: Competition Level
          description: 'Competition level: HIGH, MEDIUM, or LOW.'
        low_top_of_page_bid:
          anyOf:
            - type: number
            - type: 'null'
          title: Low Top Of Page Bid
          description: Min bid for top-of-page ad placement (~20th percentile).
        high_top_of_page_bid:
          anyOf:
            - type: number
            - type: 'null'
          title: High Top Of Page Bid
          description: Max bid for top-of-page ad placement (~80th percentile).
        spell:
          anyOf:
            - type: string
            - type: 'null'
          title: Spell
          description: Corrected spelling suggestion from Google.
        search_partners:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Search Partners
          description: Whether search partner network data is included.
        location_code:
          anyOf:
            - type: integer
            - type: 'null'
          title: Location Code
          description: Location code used for the lookup.
        language_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Language Code
          description: Language code used for the lookup.
        categories:
          anyOf:
            - items:
                type: integer
              type: array
            - type: 'null'
          title: Categories
          description: Google Ads category IDs for this keyword.
        search_intent:
          anyOf:
            - type: string
            - type: 'null'
          title: Search Intent
          description: >-
            Primary search intent: informational, commercial, transactional, or
            navigational.
        search_intent_info:
          anyOf:
            - $ref: '#/components/schemas/SearchIntentInfo'
            - type: 'null'
          description: Detailed search intent info from DataForSEO Labs.
        trend:
          anyOf:
            - items:
                $ref: '#/components/schemas/MonthlySearch'
              type: array
            - type: 'null'
          title: Trend
          description: Monthly search volume trend for the past 12 months.
        serp_features:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Serp Features
          description: >-
            SERP features present for this keyword (e.g., 'featured_snippet',
            'images').
        keyword_properties:
          anyOf:
            - $ref: '#/components/schemas/KeywordProperties'
            - type: 'null'
          description: Keyword properties (difficulty, language, word count).
        serp_info:
          anyOf:
            - $ref: '#/components/schemas/SerpInfo'
            - type: 'null'
          description: SERP information (feature types, results count).
        avg_backlinks_info:
          anyOf:
            - $ref: '#/components/schemas/AvgBacklinksInfo'
            - type: 'null'
          description: Average backlinks info for top-ranking pages.
        clickstream_info:
          anyOf:
            - $ref: '#/components/schemas/ClickstreamInfo'
            - type: 'null'
          description: Clickstream-based search data.
        ranked_serp_element:
          anyOf:
            - $ref: '#/components/schemas/RankedSerpElement'
            - type: 'null'
          description: SERP element where the domain ranks (for domain keyword lookups).
      type: object
      required:
        - keyword
      title: KeywordMetrics
      description: Full keyword research result with volume, difficulty, and trend data.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    SearchIntentInfo:
      properties:
        main_intent:
          anyOf:
            - type: string
            - type: 'null'
          title: Main Intent
          description: >-
            Primary search intent (informational, commercial, transactional,
            navigational).
        foreign_intent:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Foreign Intent
          description: Secondary/foreign search intents if detected.
      type: object
      title: SearchIntentInfo
      description: Search intent from DataForSEO Labs endpoints.
    MonthlySearch:
      properties:
        year:
          type: integer
          title: Year
          description: Calendar year (e.g., 2025).
        month:
          type: integer
          maximum: 12
          minimum: 1
          title: Month
          description: Calendar month (1–12).
        search_volume:
          type: integer
          minimum: 0
          title: Search Volume
          description: Average monthly searches.
      type: object
      required:
        - year
        - month
        - search_volume
      title: MonthlySearch
      description: Search volume for a single month.
    KeywordProperties:
      properties:
        core_keyword:
          anyOf:
            - type: string
            - type: 'null'
          title: Core Keyword
          description: The core/seed keyword.
        keyword_difficulty:
          anyOf:
            - type: number
            - type: 'null'
          title: Keyword Difficulty
          description: Keyword difficulty score (0–100).
        detected_language:
          anyOf:
            - type: string
            - type: 'null'
          title: Detected Language
          description: Detected language of the keyword.
        is_another_language:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Another Language
          description: Whether keyword is in a different language.
        words_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Words Count
          description: Number of words in the keyword.
        synonym_clustering_algorithm:
          anyOf:
            - type: string
            - type: 'null'
          title: Synonym Clustering Algorithm
          description: Synonym clustering algorithm used.
      type: object
      title: KeywordProperties
      description: Keyword properties from DataForSEO Labs endpoints.
    SerpInfo:
      properties:
        serp_item_types:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Serp Item Types
          description: SERP feature types present (featured_snippet, PAA, etc.).
        se_results_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Se Results Count
          description: Total search engine results count.
        check_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Check Url
          description: URL to check the SERP.
        last_updated_time:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Updated Time
          description: When SERP data was last updated.
      type: object
      title: SerpInfo
      description: SERP information from DataForSEO Labs endpoints.
    AvgBacklinksInfo:
      properties:
        backlinks:
          anyOf:
            - type: number
            - type: 'null'
          title: Backlinks
          description: Average number of backlinks.
        referring_domains:
          anyOf:
            - type: number
            - type: 'null'
          title: Referring Domains
          description: Average number of referring domains.
        referring_main_domains:
          anyOf:
            - type: number
            - type: 'null'
          title: Referring Main Domains
          description: Average number of referring main domains.
        rank:
          anyOf:
            - type: number
            - type: 'null'
          title: Rank
          description: Average rank.
        main_domain_rank:
          anyOf:
            - type: number
            - type: 'null'
          title: Main Domain Rank
          description: Average main domain rank.
      type: object
      title: AvgBacklinksInfo
      description: Average backlinks info from DataForSEO Labs endpoints.
    ClickstreamInfo:
      properties:
        search_volume:
          anyOf:
            - type: integer
            - type: 'null'
          title: Search Volume
          description: Clickstream-based search volume.
        gender_distribution:
          anyOf:
            - additionalProperties:
                type: number
              type: object
            - type: 'null'
          title: Gender Distribution
          description: Gender distribution (female, male).
        age_distribution:
          anyOf:
            - additionalProperties:
                type: number
              type: object
            - type: 'null'
          title: Age Distribution
          description: Age distribution by bracket.
        monthly_searches:
          anyOf:
            - items:
                $ref: '#/components/schemas/MonthlySearch'
              type: array
            - type: 'null'
          title: Monthly Searches
          description: Clickstream monthly search data.
      type: object
      title: ClickstreamInfo
      description: Clickstream data from DataForSEO Labs endpoints.
    RankedSerpElement:
      properties:
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
          description: SERP element type (organic, featured_snippet, etc.).
        rank_group:
          anyOf:
            - type: integer
            - type: 'null'
          title: Rank Group
          description: Position within the group.
        rank_absolute:
          anyOf:
            - type: integer
            - type: 'null'
          title: Rank Absolute
          description: Absolute position in SERP.
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          description: URL of the ranked page.
      type: object
      title: RankedSerpElement
      description: Ranked SERP element from DataForSEO ranked_keywords endpoint.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````