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

# List Athletes

> Retrieves the information of athletes in an organization.

### Custom Attributes

The endpoint for listing athletes allows for the use of **arbitrary query parameters** that you define based on your needs. For instance, if your organization uses custom attributes for athletes, you can pass those attributes directly in the query string.

Examples of custom attributes might include:

* `sport=MLB`
* `team=XYZ`
* `age=30`
* `position=center`
* Or any other custom attribute based on your organization's data.

These custom parameters allow you to filter athletes more precisely based on your unique dataset.
To learn more about how to properly filter athletes using custom attributes and query parameters, check out examples of [Filtering Athletes](../filtering-athletes).

***


## OpenAPI

````yaml GET /athletes
openapi: 3.0.0
info:
  title: Uplift SQL API
  version: v1
  description: >-
    API for submitting SQL queries and retrieving job IDs for the Uplift
    platform.
servers:
  - url: https://api.uplift.ai/v1
security: []
paths:
  /athletes:
    get:
      tags:
        - Athlete Management
      summary: List Athletes in Organization
      description: Retrieves the information of athletes in an organization.
      parameters:
        - name: offset
          in: query
          required: false
          description: >-
            Number of records to skip for pagination. Default is 0. 


            Read more about [Retrieving Data in
            Batches](../retrieving-data-batches) for usage examples.
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          required: false
          description: >-
            Number of records to retrieve. Maximum valid value is 500. Default
            is 100. Use with the offset query parameter to paginate and retrieve
            more than the first 500 results. 


            Read more about [Retrieving Data in
            Batches](../retrieving-data-batches) for usage examples.
          schema:
            type: integer
            default: 100
        - name: sorted_by
          in: query
          required: false
          description: >-
            Sort the records by the specified field in the record. Default is
            null.
          schema:
            type: string
            enum:
              - first_name
              - last_name
              - date_of_birth
            default: null
      responses:
        '200':
          description: Successful retrieval of athlete records.
          content:
            application/json:
              schema:
                type: object
                properties:
                  athletes:
                    type: array
                    items:
                      $ref: '#/components/schemas/Athlete'
                    description: The list of athlete records retrieved.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - bearerAuth: []
components:
  schemas:
    Athlete:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for the athlete.
        first_name:
          type: string
          description: The first name of the athlete.
        last_name:
          type: string
          description: The last name of the athlete.
        date_of_birth:
          type: string
          format: date-time
          description: The date of birth of the athlete.
        email:
          type: string
          description: The athlete's email address.
        phone:
          type: string
          description: The athlete's phone number.
        gender:
          type: string
          enum:
            - male
            - female
            - non-binary
            - prefer_not_to_say
          description: >-
            The athlete's gender. Allowed values: male, female, non-binary,
            prefer_not_to_say.
        dominant_arm:
          type: string
          enum:
            - left
            - right
            - both
          description: 'Dominant arm. Allowed values: left, right, both.'
        dominant_leg:
          type: string
          enum:
            - left
            - right
            - both
          description: 'Dominant leg. Allowed values: left, right, both.'
        activity:
          type: string
          enum:
            - baseball
            - softball
            - tennis
            - basketball
            - golf
          description: >-
            Primary sport or activity. Allowed values: baseball, softball,
            tennis, basketball, golf.
        positions:
          type: array
          items:
            type: string
          description: >-
            Positions for the athlete's activity. Requires activity to be set.
            Allowed values depend on activity: baseball and softball: pitcher,
            catcher, first_base, second_base, third_base, shortstop, left_field,
            center_field, right_field, designated_hitter. basketball:
            point_guard, shooting_guard, small_forward, power_forward, center.
            tennis and golf have no positions.
        competition_level:
          type: string
          enum:
            - youth
            - high_school
            - college
            - professional
          description: >-
            Competition level. Allowed values: youth, high_school, college,
            professional.
        height:
          type: integer
          description: The height of the athlete, in inches.
        weight:
          type: integer
          description: The weight of the athlete, in pounds (lbs).
        custom_attributes:
          type: object
          description: >-
            A set of custom key-value attributes. Keys must be strings, and
            values must also be strings.
          additionalProperties:
            type: string
        created_at:
          type: string
          format: date-time
          description: The timestamp when the athlete record was created.
        updated_at:
          type: string
          format: date-time
          description: The timestamp when the athlete record was last updated.
    Error:
      type: object
      properties:
        error:
          type: string
          description: A short error code representing the type of error.
        message:
          type: string
          description: A detailed message explaining the error.
        messages:
          type: string
          description: >-
            Create Capture only: validation detail. Multiple issues are joined
            with `; `.
  responses:
    BadRequest:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: BadRequest
            message: >-
              The request parameters are invalid. Please review the request and
              try again.
    Unauthorized:
      description: Unauthorized. Bearer token is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized
            message: Bearer token is missing or invalid.
    Forbidden:
      description: Forbidden. You do not have permission to access this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Forbidden
            message: You do not have permission to access this resource.
    TooManyRequests:
      description: Too Many Requests. The rate limit has been exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: TooManyRequests
            message: The rate limit has been exceeded. Please wait and try again later.
    InternalServerError:
      description: Internal Server Error. Something went wrong on the server.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: InternalServerError
            message: >-
              An unexpected error occurred on the server. Please try again
              later.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````