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

# Search

> Searches the scan database using query strings or CQL (Custom Query Language). 
    Returns matching scans sorted by submission date descending. 
    Supports complex filtering across multiple scan attributes. See documentation for CQL syntax details.



## OpenAPI

````yaml POST /v1/search
openapi: 3.1.0
info:
  title: urlDNA API
  description: >-
    urlDNA API documentation. This API allows you to scan, analyze, and retrieve
    insights about URLs, helping to detect potential threats such as phishing,
    malware, and scams.
  version: 1.0.0
servers:
  - url: https://api.urldna.io
security: []
paths:
  /v1/search:
    post:
      tags:
        - Search
      summary: Search
      description: >-
        Searches the scan database using query strings or CQL (Custom Query
        Language). 
            Returns matching scans sorted by submission date descending. 
            Supports complex filtering across multiple scan attributes. See documentation for CQL syntax details.
      operationId: search_v1_search_post
      parameters:
        - name: authorization
          in: header
          required: true
          schema:
            type: string
            title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Scan'
                title: Response Search V1 Search Post
        '401':
          description: 'Unauthorized: API Key is missing or invalid.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '405':
          description: >-
            Method Not Allowed: The requested HTTP method is not supported for
            this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '422':
          description: 'Unprocessable Entity: The request body or parameters are invalid.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '429':
          description: 'Too Many Requests: Rate limit exceeded.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '500':
          description: 'Internal Server Error: An unexpected error occurred.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
components:
  schemas:
    SearchRequest:
      properties:
        query:
          type: string
          maxLength: 200
          minLength: 3
          title: Query
          description: Search query string or CQL expression for filtering scans.
        max_results:
          type: integer
          maximum: 32
          minimum: 1
          title: Max Results
          description: Maximun number of scans retreived per page
          default: 32
        page:
          type: integer
          minimum: 1
          title: Page
          description: >-
            Page number for pagination (1-indexed). Pages beyond the first are
            accessible to PREMIUM users only.
          default: 1
      type: object
      required:
        - query
      title: SearchRequest
    Scan:
      properties:
        id:
          type: string
          title: Id
          description: Unique auto-generated scan identifier.
        submitted_url:
          type: string
          title: Submitted Url
          description: Original URL submitted for scanning.
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
          description: Extracted domain from the submitted URL.
        target_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Target Url
          description: Final destination URL after following all redirects.
        protocol:
          anyOf:
            - type: string
            - type: 'null'
          title: Protocol
          description: Protocol used (HTTP or HTTPS).
        device:
          $ref: '#/components/schemas/DeviceEnum'
          description: Device type used for the scan simulation (DESKTOP or MOBILE).
        user_agent:
          anyOf:
            - type: string
            - type: 'null'
          title: User Agent
          description: User agent string used to simulate the browser environment.
        http_referer:
          anyOf:
            - type: string
            - type: 'null'
          title: Http Referer
          description: >-
            HTTP Referer header value indicating the originating page for the
            request.
        nsfw:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Nsfw
          description: >-
            Indicates whether the page contains Not Safe For Work (NSFW) content
            such as nudity or adult material.
          default: false
        scanned_from:
          type: string
          title: Scanned From
          description: >-
            Country code from which the scan was initiated. Available for
            PREMIUM users only.
        origin:
          $ref: '#/components/schemas/OriginEnum'
          description: >-
            Indicates whether the scan was submitted programmatically via API or
            manually by a user.
        width:
          type: integer
          title: Width
          description: Viewport width in pixels used during the scan.
        height:
          type: integer
          title: Height
          description: Viewport height in pixels used during the scan.
        private_scan:
          type: boolean
          title: Private Scan
          description: When true, scan results are only accessible to the submitting user.
        status:
          $ref: '#/components/schemas/StatusEnum'
          description: >-
            Current scan status. PENDING and RUNNING are transient states; DONE
            and ERROR are terminal states.
        submitted_date:
          type: string
          format: date-time
          title: Submitted Date
          description: ISO 8601 timestamp when the scan was submitted.
        submitter_tags:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Submitter Tags
          description: User-defined tags for organizing and categorizing scans.
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
          description: >-
            Error code when scan status is ERROR, indicating the reason for
            failure.
      type: object
      required:
        - id
        - submitted_url
        - device
        - user_agent
        - scanned_from
        - origin
        - width
        - height
        - private_scan
        - status
        - submitted_date
      title: Scan
    APIError:
      properties:
        detail:
          type: string
          title: Detail
          example: Error description message
      type: object
      required:
        - detail
      title: APIError
    DeviceEnum:
      type: string
      enum:
        - DESKTOP
        - MOBILE
      title: DeviceEnum
    OriginEnum:
      type: string
      enum:
        - USER
        - API
        - TELEGRAM
      title: OriginEnum
    StatusEnum:
      type: string
      enum:
        - PENDING
        - RUNNING
        - DONE
        - ERROR
        - PAGE_NOT_AVAILABLE
      title: StatusEnum

````