Client API Requirements

The Client API allows users to capture custom data in FullStory via a Javascript API. FS.event, FS.setUserVars, and FS.identify each receive as arguments a JSON object containing the custom data. The contents of these JSON objects are validated before they are captured in FullStory. The validation requirements are listed in detail below.

General Payload Requirements

The payload must be a valid JSON object. For more details about the JSON format, visit The maximum payload size for a single Client API call is 512KB. Any payload larger than 512KB will be rejected.

Custom Event Name Requirements

Custom event names must be strings no longer than 250 characters. There are no reserved characters for custom event names, so any characters or symbols can be used. Custom events with names longer than 250 characters will be rejected. Empty string custom event names (i.e. "") will also be rejected.

Custom Property Name Requirements

Custom properties must be named using the pattern ident_type. Ident is a sequence of alphanumeric characters A-Z, a-z, or 0-9 and underscores ("_"). Type is a short suffix that denotes the type of the property. Custom properties names must start with an alphabetic character (A-Z or a-z). The maximum custom property name length is 512 characters, including the type suffix. There are 10 valid type suffixes, which are listed in the table below.

Type suffix





"nickname_str": "boo"



"PasswordResets_int": 49



"amtAbandonedInCart_real": 3.84


date in ISO-8601 UTC format

new Date("2014-03-11T13:19:23Z")



"didSelfServiceSignup_bool": true


list of strings

"cartIds_strs": ["a123", “b456”]


list of integers

"ids_ints": [123, 456, 789]


list of reals

"coordinates_reals": [40.7, -74.0]


list of ISO-8601 UTC format dates

 "date_range_dates": [ 

new Date("2014-03-11T13:19:23Z"),

new Date("2014-08-11T13:19:23Z")


list of booleans

"preferences_bools": [true, false, true]


In addition to these types, properties may also contain nested objects. Custom properties that take nested objects should not be type suffixed. Custom properties within nested objects must still conform to the naming requirements outlined in this section. For nested custom events, the property name including the dotted concatenation of all its parent properties must still be under the length limit of 512 characters. 


FS.event(“exampleEvent”, {
  “nonNestedProperty_str”: “example string”,
  “singleNestedProperty”: {
    “childProperty_bools”: [false, false, true, false]
  “multiNestedProperty”: {
    “childProperty1_date”: new Date("2014-03-11T13:19:23Z"),
    “childProperty2”: {
      “nestedChildProperty_int”: 1

Custom Property Value Requirements

The value of a custom property must conform to the type suffix for the property. If it doesn’t, the property will be rejected. Custom properties have a maximum value size of 8192 bytes. If the value for the property is larger than this limit, the property will be rejected.

Reserved Properties

For FS.setUserVars and FS.identify, there are five reserved property names. These properties are used for special functionality in the FullStory app. Reserved property names should not be type suffixed. These reserved property names do not apply to FS.event.

Reserved Property Name


Maximum Value Length

What it does



256 characters

Explicitly sets the unique identifier for the user



256 characters

Displays nice-looking user names



128 characters

Activates "Email this user"



256 characters




1024 characters



Custom Property Cardinality Limiting

There is an organization-wide limit on the total number of user variables, custom event names, and custom event properties that FullStory will accept. These limits are as follows:

  • Up to 500 unique user properties from FS.identify()/FS.setUserVars()
  • Up to 1,000 unique custom event names from FS.event()
  • Up to 5,000 unique custom event properties from FS.event()

Here's a few other things to keep in mind when it comes to these cardinality limits:

  • A given property name can be sent any number of times and will only count once toward the cardinality limit.

  • Properties with the same name sent with FS.setUserVars and FS.event are considered different properties for the cardinality limit.  Similarly, properties with the same name sent with FS.identify and FS.event are considered different properties with this limit.

  • Properties with the same name sent with FS.identify and FS.setUserVars are considered the same property for the cardinality limit.

  • Properties with the same property name but different event names are considered different properties for the cardinality limit.

If the cardinality limit is reached for either FS.event or FS.identify/FS.setUserVars, new property names will be rejected and will not be captured by FullStory, and no new property names will be accepted. This limit will slowly reset as property names become older than the Product analytics retention window. While we will still show new custom events in the event list, they cannot be indexed or made searchable due to the cardinality limit.

If your organization accidentally exceeded the cardinality limit and need it more quickly, contact us at

Custom Property Rate Limiting

There are per-session rate limits for the number of calls to Client APIs. There are burst limits and sustained limits. These limits are separate for FS.event and FS.identify/FS.setUserVars. For FS.event, the burst limit is 10 calls per second and the sustained limit is 30 calls per minute. For FS.setUserVars, the burst limit is 5 calls per second and the sustained limit is 12 calls per minute. If these limits are exceeded for a given time interval, subsequent Client API calls within that time interval will not be captured in FullStory.


If you notice missing or malformed Client API payloads in FullStory, this article provides guidance to troubleshoot and resolve the issue.

Need to get in touch with us?

The FullStory Team awaits your every question.

Contact us