Search Profile Pictures

Find profile-picture candidates for a search term, excluding pictures already in use

Endpoint

POST https://api.ugc.inc/media/pfp-search

Returns profile-picture candidates matching a search term. Pictures already in use as a profile picture are removed before the response is built, so two accounts cannot end up with the same picture.

Sourcing and filtering are a single call for that reason — a caller who searched and forgot to filter would create duplicate faces across their accounts and only notice much later.

Restricted API keys need the media:search scope to call this endpoint.

Request Body

search_term · string · required

What to search for. Terms that pair an identity with a style keyword work best — for example black girl selfie, asian woman aesthetic, hispanic guy selfie.

count · number

How many pictures to return. Defaults to 12, capped at 40.

Response

data · { pictures: PfpCandidate[]; search_term: string; count: number }

The candidates that survived the already-used filter. count is how many are in pictures, which can be fewer than requested — or zero, if the term found nothing or everything it found is already in use. An empty result is a signal to try a different term, not an error.

PfpCandidate.source_id · string

Stable identifier for this picture. Pass it to Filter Media by Usage or record it against a use to keep the picture out of later searches.

PfpCandidate.url · string

Full-resolution image — the one to set as an account’s profile picture.

PfpCandidate.preview_url · string

Smaller variant, for rendering a grid of options.

TypeScript

const res = await client.media.pfpSearch({
  search_term: 'black girl selfie',
  count: 5,
});

if (res.ok) {
  for (const picture of res.data.pictures) {
    console.log(picture.source_id, picture.url);
  }
}