> ## 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.

# List sessions

> Requires the `sessions:list` secret-key scope.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/sessions
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/sessions:
    get:
      tags:
        - Sessions
      summary: List sessions
      description: Requires the `sessions:list` secret-key scope.
      operationId: listSessions
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
            example: 50
        - name: cursor
          in: query
          schema:
            type: string
            example: >-
              eyJ2IjoxLCJzY29yZWRBdCI6IjIwMjYtMDQtMTBUMDY6NDI6NDIuNTE0WiIsInJvd0lkIjoiMTc3In0
        - name: verdict
          in: query
          schema:
            $ref: '#/components/schemas/Verdict'
            example: human
        - name: search
          in: query
          schema:
            type: string
            example: arm
      responses:
        '200':
          description: Session list response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionListResponse'
                example:
                  data:
                    - object: session
                      id: sid_87wfetm98myh9awj0dpt28a3kc
                      created_at: '2026-03-24T20:00:00.000Z'
                      client_user_id: user_123
                      latest_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'
                      visitor_fingerprint:
                        object: visitor_fingerprint
                        id: vid_7cyvmdfjs3rzznf8m65v3bv51m
                        confidence: 1
                        identified_at: '2026-03-24T20:00:05.000Z'
                  pagination:
                    limit: 50
                    has_more: false
                    next_cursor: >-
                      eyJ2IjoxLCJzY29yZWRBdCI6IjIwMjYtMDQtMTBUMDY6NDI6NDIuNTE0WiIsInJvd0lkIjoiMTc3In0
                  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
        '422':
          description: Invalid query parameters.
          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:
    Verdict:
      type: string
      enum:
        - bot
        - human
        - inconclusive
      example: human
    SessionListResponse:
      type: object
      additionalProperties: false
      required:
        - data
        - pagination
        - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SessionSummary'
            example:
              object: session
              id: sid_87wfetm98myh9awj0dpt28a3kc
              created_at: '2026-03-24T20:00:00.000Z'
              client_user_id: user_123
              latest_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'
              visitor_fingerprint:
                object: visitor_fingerprint
                id: vid_7cyvmdfjs3rzznf8m65v3bv51m
                confidence: 1
                identified_at: '2026-03-24T20:00:05.000Z'
          example:
            - object: session
              id: sid_87wfetm98myh9awj0dpt28a3kc
              created_at: '2026-03-24T20:00:00.000Z'
              client_user_id: user_123
              latest_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'
              visitor_fingerprint:
                object: visitor_fingerprint
                id: vid_7cyvmdfjs3rzznf8m65v3bv51m
                confidence: 1
                identified_at: '2026-03-24T20:00:05.000Z'
        pagination:
          $ref: '#/components/schemas/CursorPagination'
          example:
            limit: 50
            has_more: false
            next_cursor: >-
              eyJ2IjoxLCJzY29yZWRBdCI6IjIwMjYtMDQtMTBUMDY6NDI6NDIuNTE0WiIsInJvd0lkIjoiMTc3In0
        meta:
          $ref: '#/components/schemas/ResponseMeta'
          example:
            request_id: req_cf147349a4134208aebb8c70e25fb7e1
      example:
        data:
          - object: session
            id: sid_87wfetm98myh9awj0dpt28a3kc
            created_at: '2026-03-24T20:00:00.000Z'
            client_user_id: user_123
            latest_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'
            visitor_fingerprint:
              object: visitor_fingerprint
              id: vid_7cyvmdfjs3rzznf8m65v3bv51m
              confidence: 1
              identified_at: '2026-03-24T20:00:05.000Z'
        pagination:
          limit: 50
          has_more: false
          next_cursor: >-
            eyJ2IjoxLCJzY29yZWRBdCI6IjIwMjYtMDQtMTBUMDY6NDI6NDIuNTE0WiIsInJvd0lkIjoiMTc3In0
        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
    SessionSummary:
      type: object
      additionalProperties: false
      required:
        - object
        - id
        - created_at
        - latest_decision
        - visitor_fingerprint
        - client_user_id
      properties:
        object:
          const: session
          example: session
        id:
          $ref: '#/components/schemas/SessionId'
          example: sid_87wfetm98myh9awj0dpt28a3kc
        created_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2026-03-24T20:00:00.000Z'
        client_user_id:
          type:
            - string
            - 'null'
          maxLength: 256
          description: >-
            Customer-supplied identifier for the end user associated with this
            Foil session. Set with PATCH /v1/sessions/{sessionId}.
          example: user_123
        latest_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'
        visitor_fingerprint:
          anyOf:
            - $ref: '#/components/schemas/VisitorFingerprintLink'
              example:
                object: visitor_fingerprint
                id: vid_7cyvmdfjs3rzznf8m65v3bv51m
                confidence: 1
                identified_at: '2026-03-24T20:00:05.000Z'
            - type: 'null'
              example: null
          example:
            object: visitor_fingerprint
            id: vid_7cyvmdfjs3rzznf8m65v3bv51m
            confidence: 1
            identified_at: '2026-03-24T20:00:05.000Z'
      example:
        object: session
        id: sid_87wfetm98myh9awj0dpt28a3kc
        created_at: '2026-03-24T20:00:00.000Z'
        client_user_id: user_123
        latest_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'
        visitor_fingerprint:
          object: visitor_fingerprint
          id: vid_7cyvmdfjs3rzznf8m65v3bv51m
          confidence: 1
          identified_at: '2026-03-24T20:00:05.000Z'
    CursorPagination:
      type: object
      additionalProperties: false
      required:
        - limit
        - has_more
      properties:
        limit:
          type: integer
          minimum: 1
          maximum: 200
          example: 50
        has_more:
          type: boolean
          example: false
        next_cursor:
          type: string
          example: >-
            eyJ2IjoxLCJzY29yZWRBdCI6IjIwMjYtMDQtMTBUMDY6NDI6NDIuNTE0WiIsInJvd0lkIjoiMTc3In0
      example:
        limit: 50
        has_more: false
        next_cursor: >-
          eyJ2IjoxLCJzY29yZWRBdCI6IjIwMjYtMDQtMTBUMDY6NDI6NDIuNTE0WiIsInJvd0lkIjoiMTc3In0
    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
    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'
    VisitorFingerprintLink:
      type: object
      additionalProperties: false
      required:
        - object
        - id
        - confidence
        - identified_at
      properties:
        object:
          const: visitor_fingerprint
          example: visitor_fingerprint
        id:
          $ref: '#/components/schemas/FingerprintId'
          example: vid_7cyvmdfjs3rzznf8m65v3bv51m
        confidence:
          anyOf:
            - type: integer
              minimum: 0
              maximum: 100
              example: 1
            - type: 'null'
              example: null
          example: 1
        identified_at:
          type:
            - string
            - 'null'
          format: date-time
          example: '2026-03-24T20:00:05.000Z'
      example:
        object: visitor_fingerprint
        id: vid_7cyvmdfjs3rzznf8m65v3bv51m
        confidence: 1
        identified_at: '2026-03-24T20:00:05.000Z'
    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
    EventId:
      type: string
      pattern: ^evt_[0123456789abcdefghjkmnpqrstvwxyz]{26}$
      example: evt_srwqc0yqhz4bxvtrdtf69q7vkr
    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
    FingerprintId:
      type: string
      pattern: ^vid_[0123456789abcdefghjkmnpqrstvwxyz]{26}$
      example: vid_7cyvmdfjs3rzznf8m65v3bv51m
    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
    ManipulationVerdict:
      type: string
      enum:
        - none
        - low
        - medium
        - high
      example: none

````