List artists

Every credited illustrator with a card count, searchable by name.

GET/v1/artists1 creditfree plan

Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=600

Objects returned

No key yet? One call gets you one: POST /v1/accounts/free with an Idempotency-Key header and your email address returns a working key in the response. Keep the original Idempotency-Key and body for response replay for up to 24 hours, under the conditions in the quickstart. The trial is 800 credits over 30 days once the address is confirmed, no card; paid plans start at 29 € a month. See the quickstart and the pricing.

card_count is maintained by the importers rather than counted per request: recomputing it on read would be a GROUP BY over the whole catalogue for a number that changes once a day.

This response carries meta.total_count, like sets and unlike cards — a few hundred rows are cheap to count exactly.

Query parameters

Query parameters
Name	Type	Default	Description
`q`	string	—	Accent-insensitive substring match on the name, so `arita` finds `Mitsuhiro Arita`.
`orderBy`	string	-card_count	`slug`, `name` or `card_count`. Tiebreaker is `slug`.
`order_by`	string	—	Accepted snake_case spelling of `orderBy`; the same sort keys and cursor rules apply.
`limit`	integer	50	Rows per page, 1 to 250. Card and sealed lists cost 1 credit per 50 rows requested, rounded up: 50 costs 1, 51 costs 2, 250 costs 5, so ask for multiples of 50. Above 250 you get `LIMIT_EXCEEDED` — follow `links.next` instead of raising it.
`cursor`	string	—	Opaque keyset cursor from `links.next`. Never construct one; it carries the sort order it was issued for and is rejected if `orderBy` changes mid-run.

Headers

Headers
Name	Type	Default	Description
`X-Api-Key` required	string	—	Your API key. `Authorization: Bearer <key>` is accepted as an alias.
`If-None-Match`	string	—	Send back the `ETag` you stored. The API returns a strong ETag on every catalogue response, and a 304 is a header exchange: no body, no database row read.

Example request

curl -s -G "https://api.pokemontcgapi.com/v1/artists" \
  --data-urlencode "q=arita" \
  --data-urlencode "limit=3" \
  -H "X-Api-Key: $PTCG_API_KEY"

Example response

200 OK · Cache-Control: public, max-age=60, s-maxage=300, stale-while-revalidate=600

response.json

{
  "data": [
    { "slug": "mitsuhiro-arita", "name": "Mitsuhiro Arita", "card_count": 760 }
  ],
  "meta": { "limit": 3, "count": 1, "total_count": 1, "has_more": false }
}

Errors

Every error body carries error.code, error.message and error.request_id. Switch on the code, never on the message.

Errors returned by this endpoint
Status	Code	When
401	`MISSING_API_KEY`	No `X-Api-Key` header and no bearer token on a route that requires one.
401	`INVALID_API_KEY`	The key does not match any account.
400	`INVALID_PARAMETER`	A query parameter has the wrong type or an unsupported value — a non-integer `limit`, an unknown `lang`, an unknown `region`, a sort key that is not sortable.
400	`INVALID_CURSOR`	The cursor is malformed, or was issued for a different `orderBy` than the one on this request.
400	`LIMIT_EXCEEDED`	`limit` is above 250, or a batch request carries more than 100 ids.
429	`QUOTA_EXCEEDED`	Trial credits, monthly credits or the daily cap are exhausted, and `details` says which: `daily_cap` with `retry_after_s` is the trial daily cap, which resets at midnight UTC; `renews: true` with `resets_at` is the monthly quota of a paid plan; `renews: false` is the trial allowance, which never comes back. `details.next_step` carries the plan, prices and owner action, or email verification when it unlocks the full trial.
403	`PLAN_REQUIRED`	The feature is outside the plan (movers require Growth; photo recognition has 5 calls after Free email confirmation, then requires Growth), or the account subscription is canceled or suspended. Centering requires Growth or higher; Developer is excluded. After email confirmation the trial includes 5 measure and 5 confirm calls independently; grade and standards use trial credits without separate call counters. Before email confirmation, the message starts with “Confirm your email…”. Follow details.next_step when present.
403	`TRIAL_EXPIRED`	The trial has ended: the account is on the trial and its 30 days from signup are over, and this route costs credits. `details.trial_expired_at` is the date, `details.trial_days` the length, and `details.next_step` the owner handoff. Zero-cost routes — `/v1/me`, `/v1/me/usage`, the key routes and `/v1/billing/checkout` — still answer.

The full taxonomy, with what to do about each code, is on the errors page.

view this page as markdown