Ahrefs SERP Overview API

openapi: 3.2.0
info:
  title: Ahrefs SERP Overview API
  version: 3.0.0
  contact:
    name: Ahrefs
    url: https://ahrefs.com/
    email: support@ahrefs.com
  termsOfService: https://ahrefs.com/terms
  description: 'Operations tagged SERP Overview across 2 of this provider''s published API definitions: ahrefs-openapi-original.json, ahrefs-serp-overview-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.ahrefs.com/v3
  description: Ahrefs API v3
- url: https://api.ahrefs.com/v3/serp-overview
  description: Ahrefs SERP Overview
security:
- http:
  - read
tags:
- name: SERP Overview
  description: Fetch data from SERP Overview report
paths:
  /serp-overview/serp-overview:
    get:
      tags:
      - SERP Overview
      summary: SERP Overview
      description: ''
      operationId: serp-overview.serp-overview
      parameters:
      - description: A comma-separated list of columns to return. See response schema for valid column identifiers.
        required: true
        explode: false
        schema:
          type: string
        name: select
        in: query
      - description: A comma-separated list of SERP feature types to filter by. Only positions whose `type` includes at least one of the given values are returned. If not specified, positions of all types are returned.
        required: false
        explode: false
        schema:
          type: string
          enum:
          - paid_top
          - paid_bottom
          - paid_right
          - paid_sitelink
          - organic
          - sitelink
          - snippet
          - image
          - article
          - knowledge_card
          - knowledge_panel
          - local_pack
          - local_teaser
          - news
          - question
          - review
          - shopping
          - tweet
          - spelling
          - video
          - discussion
          - ai_overview
          - ai_overview_sitelink
          - organic_shopping
          - image_th
          - video_th
          - ai_overview_found
          default: ''
        name: type
        in: query
      - description: The number of top organic SERP positions to return. If not specified, all available positions will be returned.
        required: false
        explode: false
        schema:
          type: integer
        name: top_positions
        in: query
      - description: A timestamp on which the last available SERP Overview is returned in YYYY-MM-DDThh:mm:ss format. If it is not specified, the most recent SERP Overview is returned.
        required: false
        explode: false
        schema:
          type: string
          format: date-time
        name: date
        in: query
      - description: A two-letter country code (ISO 3166-1 alpha-2).
        required: true
        explode: false
        schema:
          type: string
          enum:
          - ad
          - ae
          - af
          - ag
          - ai
          - al
          - am
          - ao
          - ar
          - as
          - at
          - au
          - aw
          - az
          - ba
          - bb
          - bd
          - be
          - bf
          - bg
          - bh
          - bi
          - bj
          - bn
          - bo
          - br
          - bs
          - bt
          - bw
          - by
          - bz
          - ca
          - cd
          - cf
          - cg
          - ch
          - ci
          - ck
          - cl
          - cm
          - cn
          - co
          - cr
          - cu
          - cv
          - cy
          - cz
          - de
          - dj
          - dk
          - dm
          - do
          - dz
          - ec
          - ee
          - eg
          - es
          - et
          - fi
          - fj
          - fm
          - fo
          - fr
          - ga
          - gb
          - gd
          - ge
          - gf
          - gg
          - gh
          - gi
          - gl
          - gm
          - gn
          - gp
          - gq
          - gr
          - gt
          - gu
          - gy
          - hk
          - hn
          - hr
          - ht
          - hu
          - id
          - ie
          - il
          - im
          - in
          - iq
          - is
          - it
          - je
          - jm
          - jo
          - jp
          - ke
          - kg
          - kh
          - ki
          - kn
          - kr
          - kw
          - ky
          - kz
          - la
          - lb
          - lc
          - li
          - lk
          - ls
          - lt
          - lu
          - lv
          - ly
          - ma
          - mc
          - md
          - me
          - mg
          - mk
          - ml
          - mm
          - mn
          - mq
          - mr
          - ms
          - mt
          - mu
          - mv
          - mw
          - mx
          - my
          - mz
          - na
          - nc
          - ne
          - ng
          - ni
          - nl
          - 'no'
          - np
          - nr
          - nu
          - nz
          - om
          - pa
          - pe
          - pf
          - pg
          - ph
          - pk
          - pl
          - pn
          - pr
          - ps
          - pt
          - py
          - qa
          - re
          - ro
          - rs
          - ru
          - rw
          - sa
          - sb
          - sc
          - se
          - sg
          - sh
          - si
          - sk
          - sl
          - sm
          - sn
          - so
          - sr
          - st
          - sv
          - td
          - tg
          - th
          - tj
          - tk
          - tl
          - tm
          - tn
          - to
          - tr
          - tt
          - tw
          - tz
          - ua
          - ug
          - us
          - uy
          - uz
          - vc
          - ve
          - vg
          - vi
          - vn
          - vu
          - ws
          - ye
          - yt
          - za
          - zm
          - zw
        name: country
        in: query
      - description: The keyword to return SERP Overview for.
        required: true
        explode: false
        schema:
          type: string
        name: keyword
        in: query
      - $ref: '#/components/parameters/serp-overview.output_json_php_xml'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serp-overview.serp-overview'
            application/xml:
              schema:
                $ref: '#/components/schemas/serp-overview.serp-overview'
        '400':
          $ref: '#/components/responses/serp-overview.error_400'
        '401':
          $ref: '#/components/responses/serp-overview.error_401'
        '403':
          $ref: '#/components/responses/serp-overview.error_403'
        '429':
          $ref: '#/components/responses/serp-overview.error_429'
        '500':
          $ref: '#/components/responses/serp-overview.error_500'
    servers:
    - url: https://api.ahrefs.com/v3
      description: Ahrefs API v3
  /serp-overview:
    get:
      tags:
      - SERP Overview
      summary: SERP Overview
      description: ''
      operationId: serp-overview
      parameters:
      - description: A comma-separated list of columns to return. See response schema for valid column identifiers.
        required: true
        explode: false
        schema:
          type: string
        name: select
        in: query
      - description: A comma-separated list of SERP feature types to filter by. Only positions whose `type` includes at least one of the given values are returned. If not specified, positions of all types are returned.
        required: false
        explode: false
        schema:
          type: string
          enum:
          - paid_top
          - paid_bottom
          - paid_right
          - paid_sitelink
          - organic
          - sitelink
          - snippet
          - image
          - article
          - knowledge_card
          - knowledge_panel
          - local_pack
          - local_teaser
          - news
          - question
          - review
          - shopping
          - tweet
          - spelling
          - video
          - discussion
          - ai_overview
          - ai_overview_sitelink
          - organic_shopping
          - image_th
          - video_th
          - ai_overview_found
          default: ''
        name: type
        in: query
      - description: The number of top organic SERP positions to return. If not specified, all available positions will be returned.
        required: false
        explode: false
        schema:
          type: integer
        name: top_positions
        in: query
      - description: A timestamp on which the last available SERP Overview is returned in YYYY-MM-DDThh:mm:ss format. If it is not specified, the most recent SERP Overview is returned.
        required: false
        explode: false
        schema:
          type: string
          format: date-time
        name: date
        in: query
      - description: A two-letter country code (ISO 3166-1 alpha-2).
        required: true
        explode: false
        schema:
          type: string
          enum:
          - ad
          - ae
          - af
          - ag
          - ai
          - al
          - am
          - ao
          - ar
          - as
          - at
          - au
          - aw
          - az
          - ba
          - bb
          - bd
          - be
          - bf
          - bg
          - bh
          - bi
          - bj
          - bn
          - bo
          - br
          - bs
          - bt
          - bw
          - by
          - bz
          - ca
          - cd
          - cf
          - cg
          - ch
          - ci
          - ck
          - cl
          - cm
          - cn
          - co
          - cr
          - cu
          - cv
          - cy
          - cz
          - de
          - dj
          - dk
          - dm
          - do
          - dz
          - ec
          - ee
          - eg
          - es
          - et
          - fi
          - fj
          - fm
          - fo
          - fr
          - ga
          - gb
          - gd
          - ge
          - gf
          - gg
          - gh
          - gi
          - gl
          - gm
          - gn
          - gp
          - gq
          - gr
          - gt
          - gu
          - gy
          - hk
          - hn
          - hr
          - ht
          - hu
          - id
          - ie
          - il
          - im
          - in
          - iq
          - is
          - it
          - je
          - jm
          - jo
          - jp
          - ke
          - kg
          - kh
          - ki
          - kn
          - kr
          - kw
          - ky
          - kz
          - la
          - lb
          - lc
          - li
          - lk
          - ls
          - lt
          - lu
          - lv
          - ly
          - ma
          - mc
          - md
          - me
          - mg
          - mk
          - ml
          - mm
          - mn
          - mq
          - mr
          - ms
          - mt
          - mu
          - mv
          - mw
          - mx
          - my
          - mz
          - na
          - nc
          - ne
          - ng
          - ni
          - nl
          - 'no'
          - np
          - nr
          - nu
          - nz
          - om
          - pa
          - pe
          - pf
          - pg
          - ph
          - pk
          - pl
          - pn
          - pr
          - ps
          - pt
          - py
          - qa
          - re
          - ro
          - rs
          - ru
          - rw
          - sa
          - sb
          - sc
          - se
          - sg
          - sh
          - si
          - sk
          - sl
          - sm
          - sn
          - so
          - sr
          - st
          - sv
          - td
          - tg
          - th
          - tj
          - tk
          - tl
          - tm
          - tn
          - to
          - tr
          - tt
          - tw
          - tz
          - ua
          - ug
          - us
          - uy
          - uz
          - vc
          - ve
          - vg
          - vi
          - vn
          - vu
          - ws
          - ye
          - yt
          - za
          - zm
          - zw
        name: country
        in: query
      - description: The keyword to return SERP Overview for.
        required: true
        explode: false
        schema:
          type: string
        name: keyword
        in: query
      - $ref: '#/components/parameters/output_json_php_xml'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serp-overview'
            application/xml:
              schema:
                $ref: '#/components/schemas/serp-overview'
        '400':
          $ref: '#/components/responses/error_400'
        '401':
          $ref: '#/components/responses/error_401'
        '403':
          $ref: '#/components/responses/error_403'
        '429':
          $ref: '#/components/responses/error_429'
        '500':
          $ref: '#/components/responses/error_500'
    servers:
    - url: https://api.ahrefs.com/v3/serp-overview
      description: Ahrefs SERP Overview
components:
  responses:
    serp-overview.error_401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/serp-overview.Error_response'
        application/xml:
          schema:
            $ref: '#/components/schemas/serp-overview.Error_response'
    serp-overview.error_403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/serp-overview.Error_response'
        application/xml:
          schema:
            $ref: '#/components/schemas/serp-overview.Error_response'
    serp-overview.error_400:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/serp-overview.Error_response'
        application/xml:
          schema:
            $ref: '#/components/schemas/serp-overview.Error_response'
    serp-overview.error_500:
      description: Internal Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/serp-overview.Error_response'
        application/xml:
          schema:
            $ref: '#/components/schemas/serp-overview.Error_response'
    serp-overview.error_429:
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/serp-overview.Error_response'
        application/xml:
          schema:
            $ref: '#/components/schemas/serp-overview.Error_response'
    error_400:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_response'
        application/xml:
          schema:
            $ref: '#/components/schemas/Error_response'
    error_403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_response'
        application/xml:
          schema:
            $ref: '#/components/schemas/Error_response'
    error_500:
      description: Internal Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_response'
        application/xml:
          schema:
            $ref: '#/components/schemas/Error_response'
    error_401:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_response'
        application/xml:
          schema:
            $ref: '#/components/schemas/Error_response'
    error_429:
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_response'
        application/xml:
          schema:
            $ref: '#/components/schemas/Error_response'
  schemas:
    serp-overview.Error_response:
      properties:
        error:
          type: string
      type: object
      xml:
        name: AhrefsApiResponse
    serp-overview.serp-overview:
      properties:
        positions:
          items:
            properties:
              ahrefs_rank:
                type:
                - integer
                - 'null'
                title: ahrefs_rank
                description: 'The strength of a domain''s backlink profile compared to the other websites in our database, with rank #1 being the strongest.'
              backlinks:
                type:
                - integer
                - 'null'
                title: backlinks
                description: The total number of links from other websites pointing to a search result.
              domain_rating:
                type:
                - number
                - 'null'
                format: float
                title: domain_rating
                description: The strength of a domain’s backlink profile compared to the others in our database on a 100-point scale.
              keywords:
                type:
                - integer
                - 'null'
                title: keywords
                description: The total number of keywords that a search result ranks for in the top 100 organic positions.
              page_type:
                type:
                - string
                - 'null'
                title: page_type
                description: Comma-separated list of AI-predicted hierarchical page type paths for the ranking page. Each value is a slash-prefixed path (e.g. /Article/How_to).
              position:
                type: integer
                title: position
                description: The position of the search result in SERP.
              refdomains:
                type:
                - integer
                - 'null'
                title: refdomains
                description: (5 units) The total number of unique domains linking to a search result.
              title:
                type:
                - string
                - 'null'
                title: title
                description: The title of a ranking page.
              top_keyword:
                type:
                - string
                - 'null'
                title: top_keyword
                description: The keyword that brings the most organic traffic to a search result.
              top_keyword_volume:
                type:
                - integer
                - 'null'
                title: top_keyword_volume
                description: (10 units) An estimation of the average monthly number of searches for the top keyword over the latest known 12 months of data.
              traffic:
                type:
                - integer
                - 'null'
                title: traffic
                description: (10 units) An estimation of the monthly organic search traffic that a result gets from all the keywords that it ranks for.
              type:
                items:
                  type: string
                  enum:
                  - paid_top
                  - paid_bottom
                  - paid_right
                  - paid_sitelink
                  - organic
                  - sitelink
                  - snippet
                  - image
                  - article
                  - knowledge_card
                  - knowledge_panel
                  - local_pack
                  - local_teaser
                  - news
                  - question
                  - review
                  - shopping
                  - tweet
                  - spelling
                  - video
                  - discussion
                  - ai_overview
                  - ai_overview_sitelink
                  - organic_shopping
                  - image_th
                  - video_th
                  - ai_overview_found
                  title: type
                  description: 'The kind of the position: organic, paid, or a SERP feature.'
                type: array
                title: type
                description: 'The kind of the position: organic, paid, or a SERP feature.'
              update_date:
                type: string
                format: date-time
                title: update_date
                description: The date when we checked search engine results for a keyword.
              url:
                type:
                - string
                - 'null'
                title: url
                description: The URL of a ranking page.
              url_rating:
                type:
                - number
                - 'null'
                format: float
                title: url_rating
                description: The strength of a page's backlink profile on a 100-point logarithmic scale.
              value:
                type:
                - integer
                - 'null'
                title: value
                description: (10 units) The estimated value of a page’s monthly organic search traffic, in USD cents.
            type: object
          type: array
      type: object
      xml:
        name: AhrefsApiResponse
    Error_response:
      properties:
        error:
          type: string
      type: object
      xml:
        name: AhrefsApiResponse
    serp-overview:
      properties:
        positions:
          items:
            properties:
              ahrefs_rank:
                type:
                - integer
                - 'null'
                title: ahrefs_rank
                description: 'The strength of a domain''s backlink profile compared to the other websites in our database, with rank #1 being the strongest.'
              backlinks:
                type:
                - integer
                - 'null'
                title: backlinks
                description: The total number of links from other websites pointing to a search result.
              domain_rating:
                type:
                - number
                - 'null'
                format: float
                title: domain_rating
                description: The strength of a domain’s backlink profile compared to the others in our database on a 100-point scale.
              keywords:
                type:
                - integer
                - 'null'
                title: keywords
                description: The total number of keywords that a search result ranks for in the top 100 organic positions.
              page_type:
                type:
                - string
                - 'null'
                title: page_type
                description: Comma-separated list of AI-predicted hierarchical page type paths for the ranking page. Each value is a slash-prefixed path (e.g. /Article/How_to).
              position:
                type: integer
                title: position
                description: The position of the search result in SERP.
              refdomains:
                type:
                - integer
                - 'null'
                title: refdomains
                description: (5 units) The total number of unique domains linking to a search result.
              title:
                type:
                - string
                - 'null'
                title: title
                description: The title of a ranking page.
              top_keyword:
                type:
                - string
                - 'null'
                title: top_keyword
                description: The keyword that brings the most organic traffic to a search result.
              top_keyword_volume:
                type:
                - integer
                - 'null'
                title: top_keyword_volume
                description: (10 units) An estimation of the average monthly number of searches for the top keyword over the latest known 12 months of data.
              traffic:
                type:
                - integer
                - 'null'
                title: traffic
                description: (10 units) An estimation of the monthly organic search traffic that a result gets from all the keywords that it ranks for.
              type:
                items:
                  type: string
                  enum:
                  - paid_top
                  - paid_bottom
                  - paid_right
                  - paid_sitelink
                  - organic
                  - sitelink
                  - snippet
                  - image
                  - article
                  - knowledge_card
                  - knowledge_panel
                  - local_pack
                  - local_teaser
                  - news
                  - question
                  - review
                  - shopping
                  - tweet
                  - spelling
                  - video
                  - discussion
                  - ai_overview
                  - ai_overview_sitelink
                  - organic_shopping
                  - image_th
                  - video_th
                  - ai_overview_found
                  title: type
                  description: 'The kind of the position: organic, paid, or a SERP feature.'
                type: array
                title: type
                description: 'The kind of the position: organic, paid, or a SERP feature.'
              update_date:
                type: string
                format: date-time
                title: update_date
                description: The date when we checked search engine results for a keyword.
              url:
                type:
                - string
                - 'null'
                title: url
                description: The URL of a ranking page.
              url_rating:
                type:
                - number
                - 'null'
                format: float
                title: url_rating
                description: The strength of a page's backlink profile on a 100-point logarithmic scale.
              value:
                type:
                - integer
                - 'null'
                title: value
                description: (10 units) The estimated value of a page’s monthly organic search traffic, in USD cents.
            type: object
          type: array
      type: object
      xml:
        name: AhrefsApiResponse
  parameters:
    serp-overview.output_json_php_xml:
      description: The output format.
      required: false
      explode: false
      schema:
        type: string
        enum:
        - json
        - php
        - xml
      name: output
      in: query
    output_json_php_xml:
      description: The output format.
      required: false
      explode: false
      schema:
        type: string
        enum:
        - json
        - php
        - xml
      name: output
      in: query
  securitySchemes:
    http:
      type: http
      scheme: bearer
externalDocs:
  description: ''
  url: https://docs.ahrefs.com/docs/api/v3/
x-refined-from:
- ahrefs-openapi-original.json
- ahrefs-serp-overview-openapi.json