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

# Get Artists

> **/artist/**

## Description

**/artist/**

**Description:**
The /artist/ endpoint retrieves a list of artists based on specified criteria. It allows filtering artists by name, external ID, and searching for artists using a keyword.

**Method:**
`GET`

**Query Parameters:**

| Parameter  | Required | Description                                       |
| ---------- | -------- | ------------------------------------------------- |
| artistName | No       | Filter artists by their name.                     |
| externalId | No       | Filter artists by their external ID.              |
| page       | No       | Specifies the page number for pagination.         |
| size       | No       | Specifies the number of artists per page.         |
| catalog    | No       | Specifies whether to include catalog information. |
| q          | No       | Searches for artists using a keyword.             |
| statistics | No       | Whether to include statistical data.              |
| sort       | No       | Field to sort by.                                 |
| order      | No       | Sort order (asc or desc).                         |
| attributes | No       | Comma-separated list of attributes to include.    |
| column     | No       | Specific column to filter.                        |
| user       | No       | Filter by user ID.                                |

## Code Examples

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch('https://api.royalti.io/artist/', {
    method: 'GET',
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
    'https://api.royalti.io/artist/',
  )

  data = response.json()
  print(data)
  ```

  ```bash cURL theme={null}
  curl -X GET https://api.royalti.io/artist/ \

  ```
</CodeGroup>


## OpenAPI

````yaml get /artist/
openapi: 3.0.0
info:
  title: Royalti.io API
  description: "# Royalti API\r\n\r\nThis is the Royalti music royalty management platform API server.\r\n\r\n## Overview\r\n\r\nThe Royalti API provides comprehensive music royalty management services including:\r\n- Music publishing and writer management\r\n- Royalty processing and analytics\r\n- DDEX integration for music industry standards\r\n- File processing and pattern recognition\r\n- Payment processing and distribution\r\n\r\n## Authentication\r\n\r\nThe API uses JWT-based authentication with multiple protection levels:\r\n- Public endpoints for basic operations\r\n- Protected endpoints requiring valid JWT tokens\r\n- Admin endpoints for administrative functions\r\n\r\n## Features\r\n\r\n- Multi-dimensional royalty analytics\r\n- CWR (Collective Works Registration) support\r\n- DDEX integration for music metadata\r\n- Advanced file processing with pattern recognition\r\n- Real-time data processing with queue system"
  version: 2.6.0
  contact:
    name: Royalti.io Support
    email: support@royalti.io
    url: https://royalti.io
  license:
    name: Proprietary
    url: https://royalti.io/terms
servers:
  - url: https://api.royalti.io
    description: Production server
  - url: https://api-dev.royalti.io
    description: Development server
  - url: http://localhost:8084
    description: Local development
security:
  - bearerAuth: []
tags:
  - name: Accounting
    description: Accounting and financial transaction operations
  - name: DDEX
    description: DDEX operations (ERN/MEAD, messages, delivery, providers)
  - name: Label
    description: Label management operations
  - name: Internal Webhooks
    description: Internal system webhooks for royalty processing and downloads
  - name: Payment Webhooks
    description: Payment processor webhook endpoints
  - name: Billing Webhooks
    description: Stripe billing and subscription webhooks
  - name: Infrastructure Webhooks
    description: Cloudflare domain and SSL webhooks
  - name: Distribution Webhooks
    description: Digital distribution platform webhooks (FUGA)
paths:
  /artist/:
    get:
      tags:
        - Artist
      summary: Get Artists
      description: >-
        **/artist/**


        **Description:**

        The /artist/ endpoint retrieves a list of artists based on specified
        criteria. It allows filtering artists by name, external ID, and
        searching for artists using a keyword.


        **Method:**

        `GET`


        **Query Parameters:**


        | Parameter | Required | Description |

        | --- | --- | --- |

        | artistName | No | Filter artists by their name. |

        | externalId | No | Filter artists by their external ID. |

        | page | No | Specifies the page number for pagination. |

        | size | No | Specifies the number of artists per page. |

        | catalog | No | Specifies whether to include catalog information. |

        | q | No | Searches for artists using a keyword. |

        | statistics | No | Whether to include statistical data. |

        | sort | No | Field to sort by. |

        | order | No | Sort order (asc or desc). |

        | attributes | No | Comma-separated list of attributes to include. |

        | column | No | Specific column to filter. |

        | user | No | Filter by user ID. |
      parameters:
        - name: artistName
          in: query
          required: false
          description: Filter artists by their name
          schema:
            type: string
        - name: externalId
          in: query
          schema:
            type: string
          description: Filter artists by external ID
        - name: page
          in: query
          schema:
            type: integer
            default: 1
          description: Page number for pagination
        - name: size
          in: query
          schema:
            type: integer
            default: 10
          description: Number of items per page
        - name: catalog
          in: query
          schema:
            type: boolean
          description: Include catalog information
        - name: q
          in: query
          schema:
            type: string
          description: Search query
        - name: statistics
          in: query
          schema:
            type: boolean
          description: Include statistical data
        - name: sort
          in: query
          schema:
            type: string
            default: updatedAt
            enum:
              - updatedAt
              - createdAt
              - artistName
              - externalId
              - assets
              - products
              - count
              - royalty
          description: >
            Field to sort by. Standard fields include any artist attribute
            (e.g., artistName, externalId, updatedAt).


            When `statistics=true`, additional sortable fields become available:

            - `assets` - Number of assets associated with the artist

            - `products` - Number of products associated with the artist

            - `count` - Total stream/sales count from royalty data

            - `royalty` - Total royalty earnings
        - name: order
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
          description: Sort order
        - name: attributes
          in: query
          schema:
            type: string
          description: Comma-separated list of attributes to include
        - name: column
          in: query
          schema:
            type: string
          description: Specific column to filter
        - name: user
          in: query
          schema:
            type: string
          description: Filter by user ID
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Artist'
                  pagination:
                    type: object
                    properties:
                      totalItems:
                        type: integer
                      totalPages:
                        type: integer
                      currentPage:
                        type: integer
                      pageSize:
                        type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    Artist:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the artist
        artistName:
          type: string
          description: The artist's professional name or band name
        signDate:
          type: string
          format: date
          nullable: true
          description: Date the artist was signed to the label
        label:
          type: string
          nullable: true
          description: Label associated with the artist
        publisher:
          type: string
          nullable: true
          description: Publisher associated with the artist
        copyright:
          type: string
          nullable: true
          description: Copyright information
        externalId:
          type: string
          nullable: true
          description: External system identifier (e.g., label's internal ID)
        artistImg:
          type: string
          nullable: true
          description: URL to artist profile image
        links:
          type: object
          nullable: true
          description: Social media and platform links
          additionalProperties:
            type: string
          example:
            spotify: https://open.spotify.com/artist/...
            instagram: '@artisthandle'
            youtube: https://youtube.com/@artist
        contributors:
          type: object
          nullable: true
          description: Additional contributor information
          additionalProperties: true
        TenantId:
          type: integer
          description: Tenant identifier
        realName:
          type: string
          nullable: true
          description: Artist's legal/real name
        pseudonyms:
          type: array
          nullable: true
          items:
            type: string
          description: Alternative names or aliases
        birthDate:
          type: string
          format: date
          nullable: true
          description: Artist's date of birth
        birthPlace:
          type: string
          nullable: true
          description: Artist's place of birth
        biography:
          type: string
          nullable: true
          description: Artist biography
        influences:
          type: array
          nullable: true
          items:
            type: string
          description: Musical influences
        chartHistory:
          type: array
          nullable: true
          items:
            type: object
            additionalProperties: true
          description: Chart performance history
        socialMediaVerified:
          type: object
          nullable: true
          additionalProperties:
            type: boolean
          description: Verification status for social media accounts
          example:
            instagram: true
            twitter: false
        genres:
          type: array
          nullable: true
          items:
            type: string
          description: Musical genres
        instruments:
          type: array
          nullable: true
          items:
            type: string
          description: Instruments played by the artist
        activeYears:
          type: string
          nullable: true
          description: Years active (e.g., "2010-present")
        associatedActs:
          type: array
          nullable: true
          items:
            type: string
          description: Other bands or artists associated with
        recordingName:
          type: string
          nullable: true
          description: Name used for recording credits
        nationality:
          type: string
          nullable: true
          description: Artist's nationality
        gender:
          type: string
          nullable: true
          description: Artist's gender
        website:
          type: string
          nullable: true
          description: Official website URL
        fanClubUrl:
          type: string
          nullable: true
          description: Fan club or community URL
        managementInfo:
          type: object
          nullable: true
          additionalProperties: true
          description: Management contact and details
        bookingInfo:
          type: object
          nullable: true
          additionalProperties: true
          description: Booking agent and contact details
        createdAt:
          type: string
          format: date-time
          description: Record creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: error
              message:
                type: string
                example: Invalid request parameters
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: error
              message:
                type: string
                example: Unauthorized
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: error
              message:
                type: string
                example: Resource not found
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                example: error
              message:
                type: string
                example: Internal server error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        JWT Authorization header using the Bearer scheme. Format: "Bearer
        {token}"

````