> ## Documentation Index > Fetch the complete documentation index at: https://usefoil.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve one visitor fingerprint > Requires the `fingerprints:read` secret-key scope. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/fingerprints/{visitorId} openapi: 3.1.0 info: title: Foil API version: '2026-03-25' description: >- Customer-facing Foil server APIs for sessions, visitor fingerprints, organizations, and API keys. servers: - url: https://api.usefoil.com description: Production security: [] tags: - name: Sessions description: Durable session readback endpoints. - name: Visitor fingerprints description: Durable visitor fingerprint readback endpoints. - name: Organizations description: Organization lifecycle endpoints. - name: API Keys description: Organization API key lifecycle endpoints. - name: Gate description: >- Registry, organization-owned services, signup sessions, agent tokens, and dashboard login sessions. - name: Gate Webhooks description: Outbound Gate webhook delivery contracts. - name: Webhooks description: Manage webhook endpoints, subscriptions, and outgoing event delivery. - name: Events description: Inspect organization events and their webhook delivery attempts. paths: /v1/fingerprints/{visitorId}: get: tags: - Visitor fingerprints summary: Retrieve one visitor fingerprint description: Requires the `fingerprints:read` secret-key scope. operationId: getVisitorFingerprint parameters: - name: visitorId in: path required: true schema: $ref: '#/components/schemas/FingerprintId' example: vid_7cyvmdfjs3rzznf8m65v3bv51m responses: '200': description: Visitor fingerprint detail response. content: application/json: schema: $ref: '#/components/schemas/VisitorFingerprintDetailResponse' example: data: object: visitor_fingerprint id: vid_7cyvmdfjs3rzznf8m65v3bv51m lifecycle: first_seen_at: '2026-03-01T18:22:11.000Z' last_seen_at: '2026-03-24T20:00:05.000Z' seen_count: 14 expires_at: '2026-03-24T20:00:05.000Z' latest_request: user_agent: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 ip_address: 203.0.113.10 storage: cookies: true local_storage: true indexed_db: true service_worker: true window_name: true anchors: webgl_hash: '123456789' parameters_hash: '-1234567890' audio_hash: '1234567890' components: vector: - 1.5 activity: sessions: - session_id: sid_87wfetm98myh9awj0dpt28a3kc decision: event_id: evt_srwqc0yqhz4bxvtrdtf69q7vkr verdict: human risk_score: 94 phase: snapshot is_provisional: false manipulation: score: 1 verdict: none evaluation_duration_ms: 123 evaluated_at: '2026-03-24T20:00:05.000Z' request: url: https://app.acme.co/signup user_agent: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 ip_address: 203.0.113.10 screen_size: 1440x900 is_touch_capable: true score_breakdown: categories: primary: 1 meta: request_id: req_cf147349a4134208aebb8c70e25fb7e1 '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' example: error: code: request.validation_failed message: Observation payload failed validation. status: 1 retryable: true request_id: req_cf147349a4134208aebb8c70e25fb7e1 docs_url: https://app.acme.co/signup details: fields: - name: Acme Growth Workspace issue: required expected: string received: any_of allowed_values: - verified header_name: x-forwarded-for parameter_set: browser_fingerprint next_action: retry '403': description: Secret key required. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' example: error: code: request.validation_failed message: Observation payload failed validation. status: 1 retryable: true request_id: req_cf147349a4134208aebb8c70e25fb7e1 docs_url: https://app.acme.co/signup details: fields: - name: Acme Growth Workspace issue: required expected: string received: any_of allowed_values: - verified header_name: x-forwarded-for parameter_set: browser_fingerprint next_action: retry '404': description: Visitor fingerprint not found. content: application/json: schema: $ref: '#/components/schemas/ApiErrorEnvelope' example: error: code: request.validation_failed message: Observation payload failed validation. status: 1 retryable: true request_id: req_cf147349a4134208aebb8c70e25fb7e1 docs_url: https://app.acme.co/signup details: fields: - name: Acme Growth Workspace issue: required expected: string received: any_of allowed_values: - verified header_name: x-forwarded-for parameter_set: browser_fingerprint next_action: retry components: schemas: FingerprintId: type: string pattern: ^vid_[0123456789abcdefghjkmnpqrstvwxyz]{26}$ example: vid_7cyvmdfjs3rzznf8m65v3bv51m VisitorFingerprintDetailResponse: type: object additionalProperties: false required: - data - meta properties: data: $ref: '#/components/schemas/VisitorFingerprintDetail' example: object: visitor_fingerprint id: vid_7cyvmdfjs3rzznf8m65v3bv51m lifecycle: first_seen_at: '2026-03-01T18:22:11.000Z' last_seen_at: '2026-03-24T20:00:05.000Z' seen_count: 14 expires_at: '2026-03-24T20:00:05.000Z' latest_request: user_agent: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 ip_address: 203.0.113.10 storage: cookies: true local_storage: true indexed_db: true service_worker: true window_name: true anchors: webgl_hash: '123456789' parameters_hash: '-1234567890' audio_hash: '1234567890' components: vector: - 1.5 activity: sessions: - session_id: sid_87wfetm98myh9awj0dpt28a3kc decision: event_id: evt_srwqc0yqhz4bxvtrdtf69q7vkr verdict: human risk_score: 94 phase: snapshot is_provisional: false manipulation: score: 1 verdict: none evaluation_duration_ms: 123 evaluated_at: '2026-03-24T20:00:05.000Z' request: url: https://app.acme.co/signup user_agent: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 ip_address: 203.0.113.10 screen_size: 1440x900 is_touch_capable: true score_breakdown: categories: primary: 1 meta: $ref: '#/components/schemas/ResponseMeta' example: request_id: req_cf147349a4134208aebb8c70e25fb7e1 example: data: object: visitor_fingerprint id: vid_7cyvmdfjs3rzznf8m65v3bv51m lifecycle: first_seen_at: '2026-03-01T18:22:11.000Z' last_seen_at: '2026-03-24T20:00:05.000Z' seen_count: 14 expires_at: '2026-03-24T20:00:05.000Z' latest_request: user_agent: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 ip_address: 203.0.113.10 storage: cookies: true local_storage: true indexed_db: true service_worker: true window_name: true anchors: webgl_hash: '123456789' parameters_hash: '-1234567890' audio_hash: '1234567890' components: vector: - 1.5 activity: sessions: - session_id: sid_87wfetm98myh9awj0dpt28a3kc decision: event_id: evt_srwqc0yqhz4bxvtrdtf69q7vkr verdict: human risk_score: 94 phase: snapshot is_provisional: false manipulation: score: 1 verdict: none evaluation_duration_ms: 123 evaluated_at: '2026-03-24T20:00:05.000Z' request: url: https://app.acme.co/signup user_agent: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 ip_address: 203.0.113.10 screen_size: 1440x900 is_touch_capable: true score_breakdown: categories: primary: 1 meta: request_id: req_cf147349a4134208aebb8c70e25fb7e1 ApiErrorEnvelope: type: object additionalProperties: false required: - error properties: error: $ref: '#/components/schemas/PublicError' example: code: request.validation_failed message: Observation payload failed validation. status: 1 retryable: true request_id: req_cf147349a4134208aebb8c70e25fb7e1 docs_url: https://app.acme.co/signup details: fields: - name: Acme Growth Workspace issue: required expected: string received: any_of allowed_values: - verified header_name: x-forwarded-for parameter_set: browser_fingerprint next_action: retry example: error: code: request.validation_failed message: Observation payload failed validation. status: 1 retryable: true request_id: req_cf147349a4134208aebb8c70e25fb7e1 docs_url: https://app.acme.co/signup details: fields: - name: Acme Growth Workspace issue: required expected: string received: any_of allowed_values: - verified header_name: x-forwarded-for parameter_set: browser_fingerprint next_action: retry VisitorFingerprintDetail: type: object additionalProperties: false required: - object - id - lifecycle - latest_request - storage - anchors - components - activity properties: object: const: visitor_fingerprint example: visitor_fingerprint id: $ref: '#/components/schemas/FingerprintId' example: vid_7cyvmdfjs3rzznf8m65v3bv51m lifecycle: $ref: '#/components/schemas/VisitorFingerprintLifecycle' example: first_seen_at: '2026-03-01T18:22:11.000Z' last_seen_at: '2026-03-24T20:00:05.000Z' seen_count: 14 expires_at: '2026-03-24T20:00:05.000Z' latest_request: $ref: '#/components/schemas/VisitorFingerprintLatestRequest' example: user_agent: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 ip_address: 203.0.113.10 storage: $ref: '#/components/schemas/VisitorFingerprintStorage' example: cookies: true local_storage: true indexed_db: true service_worker: true window_name: true anchors: $ref: '#/components/schemas/VisitorFingerprintAnchors' example: webgl_hash: '123456789' parameters_hash: '-1234567890' audio_hash: '1234567890' components: $ref: '#/components/schemas/VisitorFingerprintComponents' example: vector: - 1.5 activity: $ref: '#/components/schemas/VisitorFingerprintActivity' example: sessions: - session_id: sid_87wfetm98myh9awj0dpt28a3kc decision: event_id: evt_srwqc0yqhz4bxvtrdtf69q7vkr verdict: human risk_score: 94 phase: snapshot is_provisional: false manipulation: score: 1 verdict: none evaluation_duration_ms: 123 evaluated_at: '2026-03-24T20:00:05.000Z' request: url: https://app.acme.co/signup user_agent: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 ip_address: 203.0.113.10 screen_size: 1440x900 is_touch_capable: true score_breakdown: categories: primary: 1 example: object: visitor_fingerprint id: vid_7cyvmdfjs3rzznf8m65v3bv51m lifecycle: first_seen_at: '2026-03-01T18:22:11.000Z' last_seen_at: '2026-03-24T20:00:05.000Z' seen_count: 14 expires_at: '2026-03-24T20:00:05.000Z' latest_request: user_agent: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 ip_address: 203.0.113.10 storage: cookies: true local_storage: true indexed_db: true service_worker: true window_name: true anchors: webgl_hash: '123456789' parameters_hash: '-1234567890' audio_hash: '1234567890' components: vector: - 1.5 activity: sessions: - session_id: sid_87wfetm98myh9awj0dpt28a3kc decision: event_id: evt_srwqc0yqhz4bxvtrdtf69q7vkr verdict: human risk_score: 94 phase: snapshot is_provisional: false manipulation: score: 1 verdict: none evaluation_duration_ms: 123 evaluated_at: '2026-03-24T20:00:05.000Z' request: url: https://app.acme.co/signup user_agent: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 ip_address: 203.0.113.10 screen_size: 1440x900 is_touch_capable: true score_breakdown: categories: primary: 1 ResponseMeta: type: object additionalProperties: false required: - request_id properties: request_id: $ref: '#/components/schemas/RequestId' example: req_cf147349a4134208aebb8c70e25fb7e1 example: request_id: req_cf147349a4134208aebb8c70e25fb7e1 PublicError: type: object additionalProperties: false required: - code - message - status - retryable - request_id properties: code: type: string x-foil-known-values-ref: '#/components/schemas/KnownPublicErrorCode' example: request.validation_failed message: type: string example: Observation payload failed validation. status: type: integer example: 1 retryable: type: boolean example: true request_id: $ref: '#/components/schemas/RequestId' example: req_cf147349a4134208aebb8c70e25fb7e1 docs_url: type: string format: uri example: https://app.acme.co/signup details: $ref: '#/components/schemas/ApiErrorDetails' example: fields: - name: Acme Growth Workspace issue: required expected: string received: any_of allowed_values: - verified header_name: x-forwarded-for parameter_set: browser_fingerprint next_action: retry example: code: request.validation_failed message: Observation payload failed validation. status: 1 retryable: true request_id: req_cf147349a4134208aebb8c70e25fb7e1 docs_url: https://app.acme.co/signup details: fields: - name: Acme Growth Workspace issue: required expected: string received: any_of allowed_values: - verified header_name: x-forwarded-for parameter_set: browser_fingerprint next_action: retry VisitorFingerprintLifecycle: type: object additionalProperties: false required: - first_seen_at - last_seen_at - seen_count - expires_at properties: first_seen_at: type: string format: date-time example: '2026-03-01T18:22:11.000Z' last_seen_at: type: string format: date-time example: '2026-03-24T20:00:05.000Z' seen_count: type: integer minimum: 0 example: 14 expires_at: type: string format: date-time example: '2026-03-24T20:00:05.000Z' example: first_seen_at: '2026-03-01T18:22:11.000Z' last_seen_at: '2026-03-24T20:00:05.000Z' seen_count: 14 expires_at: '2026-03-24T20:00:05.000Z' VisitorFingerprintLatestRequest: type: object additionalProperties: false required: - user_agent - ip_address properties: user_agent: type: string example: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 ip_address: type: string example: 203.0.113.10 example: user_agent: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 ip_address: 203.0.113.10 VisitorFingerprintStorage: type: object additionalProperties: false required: - cookies - local_storage - indexed_db - service_worker - window_name properties: cookies: type: boolean example: true local_storage: type: boolean example: true indexed_db: type: boolean example: true service_worker: type: boolean example: true window_name: type: boolean example: true example: cookies: true local_storage: true indexed_db: true service_worker: true window_name: true VisitorFingerprintAnchors: type: object additionalProperties: false required: - webgl_hash - parameters_hash - audio_hash properties: webgl_hash: type: - string - 'null' example: '123456789' parameters_hash: type: - string - 'null' example: '-1234567890' audio_hash: type: - string - 'null' example: '1234567890' example: webgl_hash: '123456789' parameters_hash: '-1234567890' audio_hash: '1234567890' VisitorFingerprintComponents: type: object additionalProperties: false required: - vector properties: vector: type: array items: type: number example: 1.5 example: - 1.5 example: vector: - 1.5 VisitorFingerprintActivity: type: object additionalProperties: false required: - sessions properties: sessions: type: array items: $ref: '#/components/schemas/VisitorFingerprintActivitySession' example: session_id: sid_87wfetm98myh9awj0dpt28a3kc decision: event_id: evt_srwqc0yqhz4bxvtrdtf69q7vkr verdict: human risk_score: 94 phase: snapshot is_provisional: false manipulation: score: 1 verdict: none evaluation_duration_ms: 123 evaluated_at: '2026-03-24T20:00:05.000Z' request: url: https://app.acme.co/signup user_agent: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 ip_address: 203.0.113.10 screen_size: 1440x900 is_touch_capable: true score_breakdown: categories: primary: 1 example: - session_id: sid_87wfetm98myh9awj0dpt28a3kc decision: event_id: evt_srwqc0yqhz4bxvtrdtf69q7vkr verdict: human risk_score: 94 phase: snapshot is_provisional: false manipulation: score: 1 verdict: none evaluation_duration_ms: 123 evaluated_at: '2026-03-24T20:00:05.000Z' request: url: https://app.acme.co/signup user_agent: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 ip_address: 203.0.113.10 screen_size: 1440x900 is_touch_capable: true score_breakdown: categories: primary: 1 example: sessions: - session_id: sid_87wfetm98myh9awj0dpt28a3kc decision: event_id: evt_srwqc0yqhz4bxvtrdtf69q7vkr verdict: human risk_score: 94 phase: snapshot is_provisional: false manipulation: score: 1 verdict: none evaluation_duration_ms: 123 evaluated_at: '2026-03-24T20:00:05.000Z' request: url: https://app.acme.co/signup user_agent: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 ip_address: 203.0.113.10 screen_size: 1440x900 is_touch_capable: true score_breakdown: categories: primary: 1 RequestId: type: string pattern: ^req_[0-9a-f]{32}$ example: req_cf147349a4134208aebb8c70e25fb7e1 ApiErrorDetails: type: object properties: fields: type: array items: $ref: '#/components/schemas/ApiFieldIssue' example: name: Acme Growth Workspace issue: required expected: string received: any_of example: - name: Acme Growth Workspace issue: required expected: string received: any_of allowed_values: type: array items: type: string example: verified example: - verified header_name: type: string example: x-forwarded-for parameter_set: type: string example: browser_fingerprint next_action: type: string enum: - retry - new_session - reload_bundle - contact_support example: retry additionalProperties: true example: fields: - name: Acme Growth Workspace issue: required expected: string received: any_of allowed_values: - verified header_name: x-forwarded-for parameter_set: browser_fingerprint next_action: retry VisitorFingerprintActivitySession: type: object additionalProperties: false required: - session_id - decision - request - score_breakdown properties: session_id: $ref: '#/components/schemas/SessionId' example: sid_87wfetm98myh9awj0dpt28a3kc decision: $ref: '#/components/schemas/Decision' example: event_id: evt_srwqc0yqhz4bxvtrdtf69q7vkr verdict: human risk_score: 94 phase: snapshot is_provisional: false manipulation: score: 1 verdict: none evaluation_duration_ms: 123 evaluated_at: '2026-03-24T20:00:05.000Z' request: $ref: '#/components/schemas/RequestContext' example: url: https://app.acme.co/signup user_agent: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 ip_address: 203.0.113.10 screen_size: 1440x900 is_touch_capable: true score_breakdown: $ref: '#/components/schemas/ScoreBreakdown' example: categories: primary: 1 example: session_id: sid_87wfetm98myh9awj0dpt28a3kc decision: event_id: evt_srwqc0yqhz4bxvtrdtf69q7vkr verdict: human risk_score: 94 phase: snapshot is_provisional: false manipulation: score: 1 verdict: none evaluation_duration_ms: 123 evaluated_at: '2026-03-24T20:00:05.000Z' request: url: https://app.acme.co/signup user_agent: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 ip_address: 203.0.113.10 screen_size: 1440x900 is_touch_capable: true score_breakdown: categories: primary: 1 ApiFieldIssue: type: object additionalProperties: false required: - name - issue properties: name: type: string example: Acme Growth Workspace issue: type: string example: required expected: type: string example: string received: anyOf: - type: string example: '0' - type: number example: 1.5 - type: boolean example: true - type: 'null' example: null example: any_of example: name: Acme Growth Workspace issue: required expected: string received: any_of SessionId: type: string pattern: ^sid_[0123456789abcdefghjkmnpqrstvwxyz]{26}$ example: sid_87wfetm98myh9awj0dpt28a3kc Decision: type: object additionalProperties: false required: - event_id - verdict - risk_score - phase - is_provisional - manipulation - evaluation_duration_ms - evaluated_at properties: event_id: $ref: '#/components/schemas/EventId' example: evt_srwqc0yqhz4bxvtrdtf69q7vkr verdict: $ref: '#/components/schemas/Verdict' example: human risk_score: type: integer minimum: 0 maximum: 100 example: 94 phase: $ref: '#/components/schemas/Phase' example: snapshot is_provisional: type: boolean example: false manipulation: anyOf: - $ref: '#/components/schemas/ManipulationSummary' example: score: 1 verdict: none - type: 'null' example: null example: score: 1 verdict: none evaluation_duration_ms: type: integer minimum: 0 example: 123 evaluated_at: type: string format: date-time example: '2026-03-24T20:00:05.000Z' example: event_id: evt_srwqc0yqhz4bxvtrdtf69q7vkr verdict: human risk_score: 94 phase: snapshot is_provisional: false manipulation: score: 1 verdict: none evaluation_duration_ms: 123 evaluated_at: '2026-03-24T20:00:05.000Z' RequestContext: type: object additionalProperties: false required: - url - user_agent - ip_address - screen_size - is_touch_capable properties: url: type: string format: uri example: https://app.acme.co/signup user_agent: type: string example: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 ip_address: type: string example: 203.0.113.10 screen_size: type: - string - 'null' example: 1440x900 is_touch_capable: type: - boolean - 'null' example: true example: url: https://app.acme.co/signup user_agent: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 14_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 ip_address: 203.0.113.10 screen_size: 1440x900 is_touch_capable: true ScoreBreakdown: type: object additionalProperties: false required: - categories properties: categories: anyOf: - type: object additionalProperties: type: integer minimum: 0 maximum: 100 example: 1 example: primary: 1 - type: 'null' example: null example: primary: 1 example: categories: primary: 1 EventId: type: string pattern: ^evt_[0123456789abcdefghjkmnpqrstvwxyz]{26}$ example: evt_srwqc0yqhz4bxvtrdtf69q7vkr Verdict: type: string enum: - bot - human - inconclusive example: human Phase: type: string enum: - snapshot - behavioral example: snapshot ManipulationSummary: type: object additionalProperties: false required: - score - verdict properties: score: anyOf: - type: integer minimum: 0 maximum: 100 example: 1 - type: 'null' example: null example: 1 verdict: anyOf: - $ref: '#/components/schemas/ManipulationVerdict' example: none - type: 'null' example: null example: none example: score: 1 verdict: none ManipulationVerdict: type: string enum: - none - low - medium - high example: none ````