# Search artists

`GET` `https://streetartcities.com/api/artists`

Find artists by name, or list the artists with markers in a city or country. Results are a lighter version of what [Get an artist](/artists-api/reference/get-an-artist/) gives you.

## Query parameters

- **q** `string` · max length: 200
  Words to look for in the artist's name and other names
- **city** `string` · pattern: ^[\w-]+$
  Only artists with markers in this city, like `amsterdam`
- **country** `string` · pattern: ^[A-Za-z]{2}$
  Only artists with markers in this country, like `NL`
- **sort** `string`
  `relevance` when you pass `q`, otherwise `popular` (most artworks first). `oldest` lists the first added first
  Allowed values: `relevance`, `popular`, `oldest`
- **updatedSince** `string` · date-time · pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  Only what changed since this time, like `2026-09-01T00:00:00Z`
- **page** `integer` · >= 1 · <= 9007199254740991 · default: 1
  Which page of results, starting at 1
- **perPage** `integer` · >= 1 · <= 100 · default: 20
  How many results per page (20 by default, at most 100)

## Requirements

Needs an [access token](/authentication/tokens/). When using OAuth, the token needs the [`artists:read`](/authentication/scopes/) scope.

## Responses

### `200` The artists that match

- **items** `array ArtistSummary[]` — required
  - _Array of ArtistSummary_
    - **@type** `string` · const: Artist — required
    - **id** `string` — required
    - **title** `string` — required
    - **href** `string` — required
      Link to the artist on Street Art Cities
    - **alternativeTitles** `array string[]` — required
      Other names they go by, and other ways to spell their name
    - **logoImage** `string`
      Link to their profile picture
    - **country** `string`
      Where they're based
    - **artworksCount** `number` — required
      How many of their artworks are on the map
    - **createdAt** `string`
    - **updatedAt** `string`
- **page** `number` — required
- **perPage** `number` — required
- **total** `number` — required
  How many artists match, over all pages

### `400` Invalid request

- **error** `object` — required
  - **message** `string` — required
  - **details** `array any[]`

### `401` Not logged in

- **error** `object` — required
  - **message** `string` — required
  - **details** `array any[]`

### `403` The app doesn't have the artists:read scope

- **error** `object` — required
  - **message** `string` — required
  - **details** `array any[]`