Fetch specific Figma design-system nodes without downloading whole files

Start with the endpoint, not the whole file

If your script calls GET /v1/files/{file_key} to extract a few components, Figma returns the complete document tree. That is fine for small files, but it becomes slow and expensive as the file grows, and it increases the chance of hitting rate limits.

Use GET /v1/files/{file_key}/nodes instead. Pass a comma-separated list of node IDs—the unique identifiers Figma assigns to layers, frames, and components—and a depth value that controls how many levels of children are included. Figma responds with document, components, and componentSets maps keyed by node ID, so your code can look up a node directly instead of walking the tree.

Worked request: two components, depth 1

Run this in a terminal or CI job. You need a Figma personal access token with permission to read the file.

curl -s 'https://api.figma.com/v1/files//nodes?ids=,&depth=1' \
  -H 'X-Figma-Token: '

• <FILE_KEY> is the key from the Figma file URL.
• <NODE_ID_1> and <NODE_ID_2> are node IDs you resolved from the file, not hardcoded values that may break after a duplicate or restructure.
• depth=1 returns the requested nodes plus their immediate children. The default is 1 if you omit the parameter.

Expected check: an HTTP 200 response whose JSON contains document and components maps, with entries for the IDs you requested. Risk: a burst of requests can return HTTP 429, meaning Figma is rate-limiting the access token. Implement backoff before automating syncs.

Reading the response

The response shape lets you index directly by node ID:

{
  "document": {
    "": { ... },
    "": { ... }
  },
  "components": {
    "": { ... },
    "": { ... }
  },
  "componentSets": {}
}

This is a response shape, not actual output. Your code should check that the requested IDs exist in the maps before using them, because Figma may omit invalid or inaccessible IDs.

Limits and common mistakes

• Depth is not a type filter. Setting depth=2 includes nested children of all types; your client must still recursively inspect the subtree to find frames, components, or instances.
• Higher depth means more data. Depth defaults to 1. Each additional level increases response size and parsing time, so use the smallest depth that covers the layers you need.
• Too many IDs or too much depth can be rejected or truncated. Chunk requests by page or component group rather than sending hundreds of IDs in one call.
• Node IDs are unstable. Resolve them dynamically from the file or from Figma's REST API; do not hardcode IDs across file duplicates or major restructures.
• Images and styles are not expanded. Image fills and local styles do not include export URLs in this response. Call the images endpoint separately when you need them.
• Rate limits apply per access token. Watch for HTTP 429 and back off; inspect Figma's rate-limit response headers before scheduling frequent syncs.

Verify before you automate

1. Request one known frame ID with depth=0 and confirm the response contains only that node's properties.
2. Request the same ID with depth=2 and verify nested child layer IDs appear in the document map.
3. Send a short burst of requests and check the rate-limit headers Figma returns to confirm remaining quota before automating syncs.

When this endpoint is not the right choice

If you need every layer in a file, or you need image export URLs and local styles in the same payload, the full file endpoint or the images endpoint is more appropriate. The nodes endpoint is best when you already know which component or frame IDs you want and you want to avoid downloading unrelated design data.