Get Artists

Returns the artists your account is attached to. Row-level permissions scope the result automatically — a bare artists query returns your artists and no one else's, so no where clause is needed for the common case.

Request

query GetArtists {
  artists {
    id
    spotify_id
    name
    username
    avatar_url
    plan
    active_plan
    domains {
      id
      domain
    }
  }
}

Response

{
  "data": {
    "artists": [
      {
        "id": "3aad8009-a307-4429-a586-8b3dbe39cdda",
        "spotify_id": "1uNFoZAHBGtllmzznpCI3s",
        "name": "Example Artist",
        "username": "exampleartist",
        "avatar_url": "https://cdn.artisthub.io/avatars/....jpg",
        "plan": "pro",
        "active_plan": "pro",
        "domains": { "id": "b1f0...", "domain": "vibe.to" }
      }
    ]
  }
}

Fields

Field	Type	Description
id	uuid!	The artist ID used by nearly every other operation.
spotify_id	String	Spotify artist ID.
name	String	Display name.
username	String	ArtistHub handle.
avatar_url	String	Profile image URL.
plan	String	Subscribed plan.
active_plan	String	Plan currently in effect, which can differ from plan during a change or trial.
current_plan	String	Plan the billing system is charging for.
dsp_order	jsonb	Preferred ordering of streaming services on this artist's links.
block_bots	Boolean	Whether bot traffic is filtered from this artist's links.
emails_enabled	Boolean	Email capture enabled.
instagram_token	String	Connected Instagram token, if any.
monthly_charge	numeric	Current monthly charge.
first_billing_date, next_billing_date	date	Billing cycle.
braintree_subscription_status	String	Billing subscription state.
billing_user_id	uuid	The user who pays for this artist.

Relationships

Relationship	Kind	Description
links	array	Every smart link for this artist.
socials	array	Social profiles rendered on bio links.
domains	object	The artist's default domain record.
custom_domain_artists	array	Custom domains assigned to this artist.
pixels	array	Ad tracking pixels. See Tracking Pixels.
optins	array	Email opt-ins. See Get Subscribers.
users	array	Accounts with access to this artist.

Useful variations

One artist with counts

query ArtistOverview($id: uuid!) {
  artists_by_pk(id: $id) {
    id
    name
    links_aggregate {
      aggregate {
        count
        sum { views_total clickthroughs_total }
      }
    }
    socials { type url }
  }
}

Artist plus recent links in one call

query ArtistWithLinks($id: uuid!) {
  artists_by_pk(id: $id) {
    id
    name
    links(order_by: { created_at: desc }, limit: 10) {
      id
      domain
      path
      title
      type
      views_total
      clickthroughs_total
    }
  }
}

Look up by Spotify ID

query BySpotify($spotify_id: String!) {
  artists(where: { spotify_id: { _eq: $spotify_id } }) {
    id
    name
  }
}

Updating an artist

A manager may update a limited set of columns:

billing_user_id, block_bots, dsp_order, emails_enabled, instagram_token, sms_available, sms_enabled

mutation UpdateArtist($id: uuid!) {
  update_artists_by_pk(
    pk_columns: { id: $id }
    _set: { block_bots: true, emails_enabled: true }
  ) {
    id
    block_bots
    emails_enabled
  }
}

name, spotify_id, and plan fields are managed by ArtistHub and cannot be set through the API.

Adding and removing artists

Mutation	Purpose
add_artist(artist_spotify_id: String!): Auth	Attaches a Spotify artist to your account. Returns a refreshed Auth payload including a new token and the updated artist list.
delete_artist(artist_id: String!): SuccessBoolean	Detaches and deletes an artist.
invite_user(email: String!, artist_id: String!, coupon: String): SuccessBoolean	Invites another user to manage an artist.

WARNING

delete_artist is destructive and removes the artist's links along with it. There is no undo.

See also

• Search Artists — find artists on Spotify before attaching them
• Artist Releases — pull a catalog to build release links from
• Artist Stats — catalog-wide analytics