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

# Get Username History

> Returns the known previous usernames of a Twitter/X profile, ordered from most recent to oldest

> **Note:** Coverage depends on when the account was first observed by the system
> It is not guaranteed to capture every rename, nor to work for all profiles

Each entry includes the username string and the Unix timestamp (ms) at which it was first detected
This endpoint is subject to a stricter rate limit than the other routes



## OpenAPI

````yaml /api-specification.yaml get /username-history
openapi: 3.0.3
info:
  title: Tweet Catcher Monitor API
  description: API for managing Tweet Catcher monitoring tasks and user data
  version: 1.0.0
  contact:
    name: Tweet Catcher
    url: https://dashboard.tweet-catcher.com/support
servers:
  - url: https://monitor-api.tweet-catcher.com/pro
    description: Production server
security:
  - ApiKeyToken: []
tags:
  - name: Manage Tasks
    description: Operations for managing Tweet Catcher monitoring tasks
  - name: User Data
    description: Operations for retrieving user-related data and history
paths:
  /username-history:
    get:
      tags:
        - User Data
      summary: Get Username History
      description: >-
        Returns the known previous usernames of a Twitter/X profile, ordered
        from most recent to oldest


        > **Note:** Coverage depends on when the account was first observed by
        the system

        > It is not guaranteed to capture every rename, nor to work for all
        profiles


        Each entry includes the username string and the Unix timestamp (ms) at
        which it was first detected

        This endpoint is subject to a stricter rate limit than the other routes
      operationId: getUsernameHistory
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 20
            pattern: ^[a-zA-Z0-9_]+$
            description: Current username of the profile to check
            example: voxelpengus
          required: true
          description: Current username of the profile to check
          name: username
          in: query
      responses:
        '200':
          description: Username history returned successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    username:
                      type: string
                      example: username
                      description: Username at the time of detection
                    detected_at:
                      type: number
                      example: 1714239600
                      description: >-
                        Unix timestamp in milliseconds when this username was
                        detected
                  required:
                    - username
                    - detected_at
                description: >-
                  Array of username history entries, ordered from most recent to
                  oldest
              example:
                - username: voxelpengus
                  detected_at: 1734288454285
                - username: waitnfts
                  detected_at: 1732114683137
                - username: yisuscoin
                  detected_at: 1732036964077
                - username: basemonkies
                  detected_at: 1729444806355
                - username: baseboys_nft
                  detected_at: 1727641888036
        '400':
          description: Invalid query parameters, or the requested username is invalid
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: boolean
                    example: true
                    description: Whether an error occurred
                  message:
                    type: string
                    example: Error message
                    description: The error message
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    example:
                      email:
                        - Invalid module
                    description: The errors
                required:
                  - error
                  - message
              example:
                error: true
                message: Invalid request parameters
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: boolean
                    example: true
                    description: Whether an error occurred
                  message:
                    type: string
                    example: Error message
                    description: The error message
                required:
                  - error
                  - message
              example:
                error: true
                message: Invalid or missing authorization token
        '500':
          description: Unexpected server error
      security:
        - ApiKeyToken: []
components:
  securitySchemes:
    ApiKeyToken:
      type: apiKey
      in: header
      name: Authorization
      description: Api key for application authentication

````

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