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

# Search

> Recognise a Discord ID, a username or an invite link, decode what the input itself tells (a Discord ID carries the account's creation date), and run every lookup module. Answering `200` takes 1 search from your daily quota; `400`, `451` and `429` take none.

Give it a Discord ID, a username or an invite link in `q`: DisDog recognises which, decodes what the input itself tells, and runs every [lookup module](https://docs.dis.dog/modules.md). A search that answers `200` takes **1 search** from your quota; every refusal is free. [What takes a search →](https://docs.dis.dog/limits.md#what-takes-a-search)

## Accepted inputs

| Input | Rule | Examples | `kind` | `value` |
| - | - | - | - | - |
| Discord ID | 17 to 20 digits, a real snowflake (not in the future) | `80351110224678912` | `discord_id` | the ID |
| Invite link | `discord.gg/<code>` or `discord.com/invite/<code>`, with or without `https://` | `discord.gg/disdog` | `invite` | the code alone: `disdog` |
| Username | 2 to 32 letters, digits, `_` or `.`, not only digits; a leading `@` is dropped | `disdog`, `@DisDog` | `username` | lowercase, without `@` |
| Legacy tag | a name of 2 to 32 characters, then `#` and 4 digits | `name#1234` | `username` | as typed |

Anything else answers `400 invalid_query`. A bare code like `disdog`, without `discord.gg/`, is read as a username.

For a Discord ID, `account.createdAt` is the exact moment the account was created: Discord encodes it in the ID. A [removed ID](https://docs.dis.dog/data-removal.md) answers `451 removed_by_owner`.

## Usernames

A username is looked up by name: `lookup.matches` lists the accounts whose username or display name contains it (up to 20, best first). When one has **exactly** this username, it becomes the account: `lookup.resolvedId` and `account` hold its ID, and every module runs on it. Without an exact match, the modules answer `no_data`: pick an ID from `matches` and search again. Same thing on its own: [`GET /v1/lookup/{name}`](https://docs.dis.dog/api-reference/endpoints/lookup).

## Invite links

For an invite, `invite` holds what’s behind it, straight from Discord: the server (name, icon, description, boosts), the channel, who created the invite, member and online counts, expiry. `null` when the invite doesn’t exist or has expired. Same thing on its own: [`GET /v1/invite/{code}`](https://docs.dis.dog/api-reference/endpoints/invite).

## Module results

Each entry of `modules` has a `status`:

| `status` | Meaning |
| - | - |
| `found` | Results are in `data`. For `profile`, the same object as [`GET /v1/profile/{id}`](https://docs.dis.dog/api-reference/endpoints/profile). |
| `not_found` | The source has nothing for this input. |
| `no_data` | The module can’t answer this kind of input (the profile module needs a Discord ID). |
| `error` | The source didn’t answer. The search still counts; try again later. |
| `soon` | The module is being connected and answers nothing yet. Check [`GET /v1/modules`](https://docs.dis.dog/api-reference/endpoints/modules). |


## OpenAPI

````yaml GET /v1/search
openapi: 3.1.0
info:
  title: dis.dog API
  version: 1.0.0
  description: >-
    Discord OSINT from one key. Look up a Discord ID, a username or an invite
    and get the profile, the servers it has been seen in, its message logs, and
    the linked Roblox and guns.lol accounts. Your access key authenticates both
    the website and this API.


    **Base URL** `https://api.dis.dog`  

    **Auth** send your key as `Authorization: Bearer DD-...` (or `X-API-Key:
    DD-...`).  

    The API is included with the **Hound** and **Alpha** plans. On the free plan
    only `/v1/me` and `/v1/modules` answer; every other endpoint returns `403
    plan_has_no_api`.
servers:
  - url: https://api.dis.dog
security:
  - bearerAuth: []
paths:
  /v1/search:
    get:
      tags:
        - Search
      summary: Full search
      description: >-
        One query, every module. Send a Discord ID, a username (with or without
        `@`) or an invite link; dis.dog works out what it is and returns the
        profile, servers, messages, Roblox and guns.lol in one report. Each
        module reports its own status (`found`, `not_found`, `no_data`, `error`,
        `soon`). Counts as one search.
      parameters:
        - name: q
          in: query
          required: true
          description: Discord ID, username or invite link.
          schema:
            type: string
            minLength: 1
            maxLength: 100
            example: '80351110224678912'
      responses:
        '200':
          description: Search result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
          headers:
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateRemaining'
        '400':
          $ref: '#/components/responses/Error'
        '401':
          $ref: '#/components/responses/Error'
        '403':
          $ref: '#/components/responses/Error'
        '429':
          $ref: '#/components/responses/Error'
components:
  schemas:
    SearchResult:
      type: object
      properties:
        id:
          type: string
          description: The saved result's id; its page is dis.dog/search/<id>.
          example: srch_a1b2c3
        createdAt:
          type: string
          format: date-time
        query:
          type: string
          example: '80351110224678912'
        kind:
          type: string
          enum:
            - discord_id
            - username
            - invite
        value:
          type: string
        account:
          type:
            - object
            - 'null'
          properties:
            id:
              type: string
            createdAt:
              type: string
              format: date-time
        lookup:
          type:
            - object
            - 'null'
          description: 'Username searches: the matching accounts.'
          properties:
            resolvedId:
              type:
                - string
                - 'null'
            matches:
              type: array
              items:
                $ref: '#/components/schemas/NameMatch'
        invite:
          oneOf:
            - $ref: '#/components/schemas/Invite'
            - type: 'null'
        modules:
          type: array
          description: >-
            One entry per module. `status: found` carries a `data` field shaped
            like the matching standalone endpoint.
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              status:
                type: string
                enum:
                  - found
                  - not_found
                  - no_data
                  - error
                  - soon
              data:
                type: object
                description: Present only when status is `found`.
    NameMatch:
      type: object
      properties:
        id:
          type: string
        username:
          type: string
        displayName:
          type:
            - string
            - 'null'
        avatarUrl:
          type:
            - string
            - 'null'
        serverCount:
          type:
            - integer
            - 'null'
        lastSeenAt:
          type:
            - string
            - 'null'
          format: date-time
    Invite:
      type: object
      properties:
        code:
          type: string
          example: discord-developers
        url:
          type: string
        memberCount:
          type:
            - integer
            - 'null'
          example: 862000
        onlineCount:
          type:
            - integer
            - 'null'
        expiresAt:
          type:
            - string
            - 'null'
          format: date-time
        server:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
              example: Discord Developers
            description:
              type:
                - string
                - 'null'
            iconUrl:
              type:
                - string
                - 'null'
            bannerUrl:
              type:
                - string
                - 'null'
            createdAt:
              type:
                - string
                - 'null'
              format: date-time
            vanityCode:
              type:
                - string
                - 'null'
            boostCount:
              type:
                - integer
                - 'null'
            boostTier:
              type:
                - integer
                - 'null'
            verificationLevel:
              type:
                - integer
                - 'null'
    Error:
      type: object
      required:
        - error
      description: >-
        Every error is a flat object with an `error` code. Some add fields (for
        example `retryAfterMs` on `rate_limited`).
      properties:
        error:
          type: string
          example: plan_has_no_api
          enum:
            - invalid_request
            - invalid_id
            - invalid_name
            - invalid_invite
            - unauthorized
            - invalid_api_key
            - plan_has_no_api
            - user_not_found
            - invite_not_found
            - not_available
            - removed_by_owner
            - rate_limited
            - quota_exceeded
            - module_unavailable
            - upstream_unavailable
            - upstream_busy
            - not_found
        retryAfterMs:
          type: integer
          description: 'On `rate_limited`: wait this long before retrying.'
          example: 2000
  headers:
    RateRemaining:
      description: Searches left in today's quota (or `unlimited`).
      schema:
        type: string
        example: '498'
  responses:
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your access key, `DD-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX`. The same key is
        your website login. Keep it server-side.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.