> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fingerprint.com/llms.txt
> Use this file to discover all available pages before exploring further.

# get function

> This page contains the API reference for the JavaScript agent `get()` function or its equivalent in your frontend library. The function is not exported directly from the [@fingerprint/agent](https://www.npmjs.com/package/@fingerprint/agent) NPM package. Instead, it is a method on the agent instance returned by the [start()](/reference/js-agent-start-function) function.

The `get()` function sends an identification request to Fingerprint and returns the browser's visitor ID.

* Call `get()` only when you actually need the visitor ID.
* Wait at least 1 second between [`start()`](/reference/js-agent-start-function) and `get()` so the agent has time to collect the signals required for Identification and Smart Signals.

If you are just getting started with Fingerprint, we recommend reading the following guides first:

* [Install the JavaScript agent](/docs/install-the-javascript-agent)
* [Identify visitors](/docs/identify-visitors)

## `get()` options

### `linkedId`

> **Required**: no **Default**: `undefined` **Type**: `string` **Constraint**: the number of characters must not exceed 256

`linkedId` is a way of linking the current analysis event with a custom identifier. This will allow you to filter visit information when using the [Server API](/reference/server-api).

<CodeGroup>
  ```javascript Add a custom identifier to an analysis event theme={"theme":"github-dark-dimmed"}
  // Making an API call
  var orderId = 3936532456
  fp.get({ linkedId: orderId })
  // linkedId will be saved with this event and will be available to be queried later.
  ```
</CodeGroup>

If the information stored in `linkedId` is not available on the client when the event happens, it is possible to set it through our [Update Event Server API](/reference/server-api-update-event).

To learn more about `tag` and `linkedId` use cases, see [Linking and tagging information](/docs/tagging-information).

### `tag`

> **Required**: no **Default**: `undefined` **Type**: any simple value or an object (not arrays) **Constraint**: the size must not exceed 16KB

`tag` is a customer-provided value or an object that is saved with the identification event and returned back to you in a webhook message or Server API response. You can use `tag` to associate the visit event with other information you have about the visitor.

You can use any simple value (string, number, boolean) or an object. An object is saved as provided. A simple value (for example `123`) is returned wrapped in an object like this: `{ "tag": 123 }`.

Examples of using the `tag` option:

<CodeGroup>
  ```javascript JavaScript theme={"theme":"github-dark-dimmed"}
  fp.get({ tag: 123 });
  fp.get({ tag: "signup" });
  fp.get({ tag: { id: "456", location: { city: "Atlanta", country: "US" }});
  ```
</CodeGroup>

What comes back in a Webhook or Server API response:

<CodeGroup>
  ```json JSON theme={"theme":"github-dark-dimmed"}
  {
    "visitor_id": "nTxJ28Gt4CegeAwdWELL",
    "tag": { "tag": 123 },
    // ...
  }

  {
    "visitor_id": "nTxJ28Gt4CegeAwdWELL",
    "tag": { "tag": "signup" },
    // ...
  }

  {
    "visitor_id": "nTxJ28Gt4CegeAwdWELL",
    "tag": {
      "id": "456",
      "location": {
        "city": "Atlanta",
        "country": "US"
      }
    }
    // ...
  }
  ```
</CodeGroup>

If the information stored in `tag` is not available on the client when the event happens, it is possible to set it through our [Update Event Server API](/reference/server-api-update-event).

To learn more about `tag` and `linkedId` use cases, see [Linking and tagging information](/docs/tagging-information).

### `timeout`

> **Required**: no **Default**: `10000` **Type**: `number`

Client timeout controls the total time (both client-side and server-side) that any analysis event can run. It doesn't include the time when the page is in the background (not visible) because the browser may suspend the analysis process during that time. By default, it's 10 seconds. You can set the client-side timeout *in milliseconds* using the `timeout` option. Example usage:

<CodeGroup>
  ```javascript JavaScript theme={"theme":"github-dark-dimmed"}
  // A timeout of 20 seconds
  // An example of the client-side timeout handling
  try {
    const result = await fp.get({ timeout: 20000 })
    // ...
  } catch (error) {
    if (error.code === 'client_timeout') {
      console.log("A timeout of 20 seconds exceeded")
    }
  }
  ```
</CodeGroup>

<Warning>
  Note that setting a low timeout (less than 2000ms) could increase identification failures on weaker devices with slower internet connections.
</Warning>

## `get()` response

`fp.get()` returns a promise that resolves to a result object. Only `event_id` and `sealed_result` are always present. Every other field is conditional on either workspace configuration or the options passed to `start()` (see the field reference below). The format summary:

<CodeGroup>
  ```javascript JavaScript theme={"theme":"github-dark-dimmed"}
  const result = await fp.get()
  // response (fully-populated shape):
  {
    event_id: "8nbmT18x79m54PQ0GvPq",        // always present
    visitor_id: "2JGu1Z4d2J4IqiyzO3i4",      // absent when Zero Trust mode is enabled
    suspect_score: 10,                        // present only when Smart Signals are enabled
    sealed_result: null,                      // BinaryOutput when Sealed Client Results are enabled, else null
    cache_hit: false                          // present only when `cache` was configured in start()
  }

  // Serialize the sealed_result before transport if needed:
  const sealedResultBase64 = result.sealed_result?.base64()

  // optionally you can do the following:
  // if you will try to cast `sealed_result` into a string it will automatically call
  // toString() method which will give you the base64, eg:
  console.log(`result.sealed_result`) // will log base64 string

  // if you will try to call JSON.stringify(result.sealed_result) it will call
  // the toJSON() method which will return base64 as well, eg:
  console.log(JSON.stringify(result.sealed_result)) // will log base64 string
  ```
</CodeGroup>

<Warning>
  Three fields may be `undefined` and need explicit guards before use:

  * `visitor_id` and `suspect_score` depend on **workspace configuration** (Zero Trust mode and Smart Signals respectively).
  * `cache_hit` depends on the **`start()` configuration** (the `cache` option), not workspace settings.

  Use optional chaining (`result.visitor_id?.startsWith(...)`) or explicit `if` checks before relying on any of them.
</Warning>

### get() response fields

#### `event_id`

> **Required**: yes **Type**: `string`

The request identifier is unique for every request. Use it to request information about a specific identification request from the [Server API](/reference/server-api-get-event).

#### `visitor_id`

> **Required**: no **Type**: `string`

The browser identifier (or device identifier for mobile platforms).

In most configurations the field is always present. It contains an empty string if the visitor can't be identified (for example, a search bot). If the identification product is disabled, a dummy value is used.

The field is omitted from the response (`undefined`) when the workspace has Zero Trust mode enabled. In that case the backend does not return a visitor identifier to the client and you should retrieve it from the [Server API](/reference/server-api-get-event) using `event_id`.

#### `sealed_result`

> **Required**: yes **Type**: `BinaryOutput | null`

The field is always present in the response. It carries a `BinaryOutput` wrapper around the sealed payload when Sealed Client Results are enabled for the workspace, and `null` otherwise. See the [Sealed Client Results](/docs/sealed-client-results) guide for setup details.

`BinaryOutput` has five serialization methods:

* `base64(): string`
* `byteArray(): Uint8Array`
* `blob(): Blob`
* `toJSON(): string`
* `toString(): string`

<Note>
  The `BinaryOutput` interface is referenced inside the public `GetResult` type but is not exported as a top-level name from the package. If you need it for typing your own code, access it via `NonNullable<GetResult['sealed_result']>` (since `GetResult['sealed_result']` itself is `BinaryOutput | null`).
</Note>

#### `cache_hit`

> **Required**: no **Type**: `boolean`

The value is included if the `cache` configuration was used during the `start()` call and is:

* `true` if the `get()` response was retrieved from the cache.
* `false` if the `get()` response came directly from the Fingerprint backend.

The field is `undefined` when the `cache` option was not set in `start()`.

#### `suspect_score`

> **Required**: no **Type**: `number`

Shows the [Suspect Score](/docs/suspect-score) value of the event when the workspace has Smart Signals enabled. The field is `undefined` otherwise.