Search assets

GET https://api.iconscout.com/v3/search

Search for icons, illustrations, 3D icons, Lottie animations, or AI-generated images with rich filtering options.

Filter Reference by Asset Type

Icons (`asset=icon`)

formats[]: svg, png
styles[]: colored-outline, doodle, dualtone, flat, glyph, gradient, isometric, line, rounded, sticker, tile

Illustrations (`asset=illustration`)

formats[]: svg, png, eps
styles[]: colored-outline, doodle, dualtone, flat, glyph, gradient, isometric, line, rounded, sticker, tile

3D Icons (`asset=3d`)

formats[]: png, gltf, glb, obj, fbx, blend

Lottie Animations (`asset=lottie`)

formats[]: json, lottie, gif, mp4

AI Images (`asset=ai-image`)

formats[]: png, jpg

Use Cases

Browse trending free flat icons:

GET /v3/search?asset=icon&styles[]=flat&price=free&sort=popular

Find SVG illustrations for a keyword:

GET /v3/search?query=social-media&asset=illustration&formats[]=svg

Search Lottie animations in JSON format:

GET /v3/search?query=loading&asset=lottie&formats[]=json&sort=popular

Find 3D icons with glTF format:

GET /v3/search?query=rocket&asset=3d&formats[]=gltf

Parameters

Name In Type Notes

query query string optional
Search keyword. Use descriptive terms for best results (e.g., social-media, loading-spinner, arrow-right). Omit or leave empty to browse all assets.

asset

query

string

optional; one of icon, lottie, 3d, illustration, ai-image; default icon
Type of design asset to search.

icon — Vector icons (SVG, PNG)
illustration — Vector & raster illustrations
3d — 3D icons and models
lottie — Lottie JSON animations
ai-image — AI-generated images

price

query

string

optional; one of free, premium
Filter by licensing price tier. Omit to return all assets (free + premium).

free — Free assets only
premium — Premium assets only

sort

query

string

optional; one of relevant, popular, latest, featured; default relevant
Sort order for results.

relevant *(default)* — Best match for the query
popular — Most downloaded / viewed
latest — Recently published
featured — Editorially featured assets

formats[]

query

string[]

optional; one of svg, png, eps, jpg, json, lottie, gif, mp4, gltf, glb, obj, fbx, blend
Filter by available file format. Pass multiple values to allow any of the listed formats. Valid values depend on the asset type:

Asset	Valid formats
`icon`	`svg`, `png`
`illustration`	`svg`, `png`, `eps`
`3d`	`png`, `gltf`, `glb`, `obj`, `fbx`, `blend`
`lottie`	`json`, `lottie`, `gif`, `mp4`
`ai-image`	`png`, `jpg`

styles[]

query

string[]

optional; one of colored-outline, doodle, dualtone, flat, glyph, gradient, isometric, line, rounded, sticker, tile
Filter by visual style. Applies to icon and illustration asset types. Pass multiple values to include any of the listed styles. Available styles:

colored-outline — Outlined with color fills
doodle — Hand-drawn doodle style
dualtone — Two-tone color palette
flat — Flat design, no gradients
glyph — Solid single-color silhouette
gradient — Gradient color fills
isometric — Isometric 3D perspective
line — Thin line / outline style
rounded — Rounded corners and strokes
sticker — Sticker-style with border
tile — Tile / pattern style

orientation[] query string[] optional; one of horizontal, vertical, square, horizontal-panorama, vertical-panorama, cylindrical-panorama, spherical-panorama
Filter by orientation. Applies to non-icon asset types (e.g. illustration, 3d). Pass multiple values to include any of the listed orientations. Available orientations: horizontal, vertical, square, horizontal-panorama, vertical-panorama, cylindrical-panorama, spherical-panorama.

icon_grid query integer optional
Filter icons by their design grid size, in pixels (the icon canvas width, e.g. 24 for a 24×24 grid). Applies to asset=icon only; ignored for other asset types.

categories[] query string[] optional
Filter by category slug (e.g. business, social-media). Pass multiple values to include any of the listed categories.

contributors[] query string[] optional
Filter by contributor username. Pass multiple values to include assets from any of the listed contributors.

include_tags[] query string[] optional
Narrow results to assets tagged with all of the given tags.

exclude_tags[] query string[] optional
Exclude assets tagged with any of the given tags.

include_categories[] query string[] optional
Narrow results to assets in all of the given category slugs.

exclude_categories[] query string[] optional
Exclude assets in any of the given category slugs.

start_date query string optional
Only return assets published on or after this date (YYYY-MM-DD).

end_date query string optional
Only return assets published on or before this date (YYYY-MM-DD). Must be on or after start_date.

page query integer optional; default 1
Page number for pagination. Starts at 1. Maximum page depends on per_page (max result window: 1500 items).

per_page query integer optional; default 60
Number of results per page. Defaults vary by asset type (typically 30–60). Maximum is 200.

Responses

Status	Meaning
`200`	Paginated list of matching assets
`400`	Validation error — invalid parameter value. `data.reason` is `invalid_request`.
`401`	Unauthorized — missing or invalid Client-ID. `data.reason` is `invalid_credentials`.
`429`	Rate limit exceeded for this client. `data.reason` is `rate_limit_exceeded`. Limits are per client, per product family and per method, and are set by your plan — support can raise them for an individual client. This operation needs only `Client-ID`, but the plan limit applies only when the request also carries your `Client-Secret`. With `Client-ID` alone the caller cannot be verified, so it gets the unverified limit (60 reads a minute), counted per client id and address. Read the `X-RateLimit-*` headers, which are returned on every response the limiter admits and not only this one, rather than hard-coding a number; back off on `Retry-After`. They are absent only where the call is refused before the limiter runs — a `401` on invalid credentials. Distinct from the credit allowance, which refuses with `quota_exhausted` and is not cleared by waiting.

Examples

Search flat icons

curl -X GET 'https://api.iconscout.com/v3/search?query=social-media&asset=icon&styles[]=flat&price=free&sort=popular&per_page=20' \
  -H 'Client-ID: your-client-id'

Search Lottie animations

curl -X GET 'https://api.iconscout.com/v3/search?query=loading&asset=lottie&formats[]=json&sort=popular' \
  -H 'Client-ID: your-client-id'

Node.js fetch

const res = await fetch(
  'https://api.iconscout.com/v3/search?query=social-media&asset=icon&styles[]=flat&price=free',
  { headers: { 'Client-ID': 'your-client-id' } }
);
const { response } = await res.json();
console.log(`Found ${response.items.total} icons`);
response.items.data.forEach(icon => {
  console.log(icon.name, icon.urls.svg);
});

Python requests

import requests

params = {
    'query': 'social-media',
    'asset': 'icon',
    'styles[]': 'flat',
    'price': 'free',
    'sort': 'popular',
    'per_page': 20,
}
resp = requests.get(
    'https://api.iconscout.com/v3/search',
    params=params,
    headers={'Client-ID': 'your-client-id'},
)
data = resp.json()['response']
print(f"Found {data['items']['total']} icons")
for icon in data['items']['data']:
    print(icon['name'], icon['urls']['svg'])

Try it in the interactive reference →

Search assets

Filter Reference by Asset Type

Icons (asset=icon)

Illustrations (asset=illustration)

3D Icons (asset=3d)

Lottie Animations (asset=lottie)

AI Images (asset=ai-image)

Use Cases

Parameters

Responses

Examples

Search flat icons

Search Lottie animations

Node.js fetch

Python requests

Icons (`asset=icon`)

Illustrations (`asset=illustration`)

3D Icons (`asset=3d`)

Lottie Animations (`asset=lottie`)

AI Images (`asset=ai-image`)