Skip to main content
Question

REST API Variables


Hello there,

A tricky one: Is it intentional that when I use the GET /v1/files/:file_key/variables/local API I can get a response that contains an alias pointing to a variable that is not part of the response itself?

...
        "valuesByMode": {
          "XXXX:X": {
            "type": "VARIABLE_ALIAS",
            "id": "VariableID:XXXXX/XXXX:XXX" //<- This id is nowhere else mentioned in the response.
          },
...

Thank you!

11 replies

y_toku
Figmate
  • Community Support
  • 2487 replies
  • January 9, 2024

Hi there,

Thanks for the post! I’m checking with our internal team, and I’ll update if I have anything I can share with you. Thanks for your patience!

Toku


y_toku
Figmate
  • Community Support
  • 2487 replies
  • January 11, 2024

Hi there,

Thanks for waiting! As I asked our internal team, they think they hope to access your file so they can investigate deeply. Could you please file a case via the form here: https://help.figma.com/hc/en-us/requests/new? The support team will look into it.

Thanks for your understanding!

Toku


Hi,

I have to double check the confidentiality of the files but I will try.

Thanks!


Tim_Gremore

@y_toku I have the same situation - aliases that are nowhere to be found in the list of returned variables. Is this expected under certain conditions from /v1/files/my-file-key/variables/local ?


Glenn_Howald

I am also trying to understand this. Where can I find a VARIABLE_ALIAS?

It looks like these references are stored somewhere else. Is there a REST API to look up the contents of a variable based on its id in the format “VariableID:XXXXXXXXXXXXXXXXXXXXXX/XXX:XXX”


Glenn_Howald

I ended up getting permission to the file(s) in question and requested the local variables from an included library and was able to see more variable alias details.

I think there is still an issue because it would be nice to know where the alias is defined (to access that file directly) or to automatically follow the alias “path” or to be able to look up an aliased value directly.


James_Yang
Figmate
  • Figmate
  • 82 replies
  • November 13, 2024

We made an update a few weeks ago to include some more variables in certain cases: https://www.figma.com/developers/api#changelog

Can you check if the variable referred to in the alias is present now?


Wes Tyler
  • New Member
  • 1 reply
  • March 11, 2025

@James_Yang I’m running into a similar issue where the "id": "VariableID:XXXXX/XXXX:XXX" value is not found in the response anywhere. I confirmed that the issue is not related to deletedButReferenced, and tracked it down to multiple layers of nesting in the variables.

From the file UI:

I see that the variable is all linked up across the several collections in the file as expected:
 


It is that very top linkage from collection “08. Color Mode” variable accent/on/container/filled → collection “07. Accent Mode” variable accent/ramp/20 that is broken on the API response.


My findings on the API response:
In the response meta.variables data the “top” level accent/on/container/filled has the valuesByMode for “Dark” mode pointing to a variable alias with id VariableID:501b952efaf1e451da39f77b293530a9c7d2261a/4194:122. This id should reference accent/ramp/20 but is not found on the response.

If I look at the variables on the response I can find the  accent/ramp/20 variable, but it has an id VariableID:13206:5. On this variable I do see a “key” that matches the first segment of the missing variable id 501b952efaf1e451da39f77b293530a9c7d2261a

 

Since the variable is linking up to the final primitive #3E1C6C in the UI I feel like there is some way that I should be able to use the VariableID:13206:5 key property to calculate the linkage that seems to be missing in the API. Is this intelligible enough for you to provide guidance?


joji
  • New Member
  • 1 reply
  • May 20, 2025

I’m running into exactly this issue with the API. There are several variable aliases that point to IDs that don’t exist in the response and are therefore unresolvable via the Variables API.

The Figma UI does show the resolved value of these aliased variables, so the linkage exists somewhere. It’s just not available in the JSON response from the API.

Has anyone found any workarounds for this?


jefflee
Figmate
  • Figmate
  • 24 replies
  • May 20, 2025

Hey folks, thanks for the report and sorry you’re running into issues!

If anyone has a minimal reproduction of this issue, it would help us pinpoint the bug more quickly. Ideally, this would come in the form of a file shared with support-share@figma.com, but it’d also be helpful to get a verbal description of how your variables are set up.


jefflee
Figmate
  • Figmate
  • 24 replies
  • May 24, 2025

Thanks to help from ​@joji, I think I was able to identify the issue. It seems like the problem occurs when we have an alias chain that is at least 3 variables deep, and multiple variables are deleted.

For example, suppose we have Variable A that aliases Variable B that aliases Variable C. Then we delete Variable B and Variable C. The get-local-variables API will return Variable A and Variable B, but not Variable C.

We’ve filed a bug report for this specific issue. Please respond in thread if you think there are cases that don’t fit this description.


Reply


Cookie policy

We use cookies to enhance and personalize your experience. If you accept you agree to our full cookie policy. Learn more about our cookies.

 
Cookie settings