Client API Requirements

Please see Fullstory's developer documentation for more detailed API information:

The Fullstory API allows users to capture custom data in Fullstory via a Javascript API. Most methods 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.

Event Name Requirements

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

Property Name Requirements

Properties must be named using a sequence of alphanumeric characters (A-Z, a-z, or 0-9), underscores (_), or hyphens (-). Properties names must start with an alphabetic character (A-Z or a-z). The maximum property name length is 512 characters.

For version 1 of the Fullstory API, type suffixes in the form of _type are required for all property names. For version 2, type suffixes are no longer required. See custom properties for more information.

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. Properties within nested objects must still conform to the naming requirements outlined in this section. For nested events, the property name including the dotted concatenation of all its parent properties must still be under the length limit of 512 characters.


Property Value Requirements

The value of a property must conform to the type specified for the property. (Either suffix for version 1 or an optional schema for version 2). For version 1, if it does not, the property will be rejected. For version 2, all properties without a type will be inferred by the server. 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

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 (in version 1). These reserved property names do not apply to capturing events.

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

Displays user's email address



256 characters




1024 characters



Property Cardinality Limiting

There is an organization-wide limit on the total number of user properties, event names, and event properties that Fullstory will accept. These limits apply to properties sent by the client API as well as the HTTP API. These limits are as follows:

  • Up to 500 unique user properties
  • Up to 1,000 unique event names
  • Up to 5,000 unique event properties

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 user properties and event properties are considered different properties for the cardinality limit. 
  • Properties with the same name sent with “identify” and set user properties 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, new property names will be rejected and will not be captured by Fullstory. This limit will slowly reset as property names become older than the Product analytics retention window. 

Note: Events can still appear in the Event List in Session Replay even when the limit is reached. However, they cannot be indexed or searched for.

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


Property Rate Limiting

There are per-session rate limits for the number of calls to Client APIs. There are burst limits and sustained limits.

  • User properties have a burst limit of 10/second and a sustained limit of 30/minute.
  • Events have a burst limit of 40/second and a sustained limit of 60/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.

Ask the Community Technical Support