> ## 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. # Break down sessions > Counts the sessions that match the filters, grouped by one dimension, with each group's bot, human and inconclusive counts. Counts lag new scores by up to five minutes. Requires the `sessions:list` secret-key scope. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/sessions/breakdown 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: Session readback endpoints. - name: Visitor fingerprints description: Visitor fingerprint readback endpoints. - name: Organizations description: Organization lifecycle endpoints. - name: API Keys description: Organization API key lifecycle endpoints. - 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/breakdown: get: tags: - Sessions summary: Break down sessions description: >- Counts the sessions that match the filters, grouped by one dimension, with each group's bot, human and inconclusive counts. Counts lag new scores by up to five minutes. Requires the `sessions:list` secret-key scope. operationId: getSessionBreakdown parameters: - name: group_by in: query required: true description: >- The dimension to group by. `browser_label` is the browser and major version (for example `Chrome 141`); `city` groups pair each city with its `country_code`. schema: type: string enum: - browser - browser_label - platform - verdict - country - city - asn example: browser - name: limit in: query description: >- The number of groups to return, largest first. Sessions in the remaining groups are counted in `other`. schema: type: integer minimum: 1 maximum: 500 default: 50 example: 50 - name: verdict in: query description: Only sessions whose current verdict is this value. schema: $ref: '#/components/schemas/Verdict' example: human - name: platform in: query schema: type: string enum: - ios - android - macos - windows - linux example: ios - name: browser in: query schema: type: string enum: - chrome - safari - firefox - edge - webview - arc - helium example: chrome - name: browser_label in: query description: Exact browser label, as returned in a `browser_label` breakdown. schema: type: string maxLength: 200 example: Chrome 141 - name: country in: query description: ISO 3166-1 alpha-2 country code of the session's IP address. schema: type: string pattern: ^[A-Za-z]{2}$ example: US - name: city in: query description: >- City of the session's IP address. Combine with `country` to pick one city of that name. schema: type: string maxLength: 200 example: Austin - name: asn in: query description: >- Autonomous system number of the session's IP address, with or without the `AS` prefix. schema: type: string pattern: ^(AS|as)?[0-9]{1,10}$ example: AS7922 - name: client_user_id in: query description: Only sessions whose `client_user_id` is exactly this value. schema: type: string minLength: 1 maxLength: 256 example: user_123 - name: since in: query description: Only sessions created at or after this time. schema: type: string format: date-time example: '2026-09-01T00:00:00Z' - name: until in: query description: Only sessions created before this time. schema: type: string format: date-time example: '2026-10-01T00:00:00Z' responses: '200': description: Session counts per group. content: application/json: schema: $ref: '#/components/schemas/SessionBreakdownResponse' example: data: object: session_breakdown group_by: browser total: sessions: 48210 bots: 3105 humans: 39874 inconclusive: 5231 groups: - value: chrome label: chrome sessions: 21480 bots: 1932 humans: 17201 inconclusive: 2347 other: sessions: 26730 bots: 1173 humans: 22673 inconclusive: 2884 group_count: 7 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 '503': description: >- The breakdown did not finish in time. Narrow the time range or add filters. 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 SessionBreakdownResponse: type: object additionalProperties: false required: - data - meta properties: data: $ref: '#/components/schemas/SessionBreakdown' example: object: session_breakdown group_by: browser total: sessions: 48210 bots: 3105 humans: 39874 inconclusive: 5231 groups: - value: chrome label: chrome country_code: US sessions: 21480 bots: 1932 humans: 17201 inconclusive: 2347 other: sessions: 26730 bots: 1173 humans: 22673 inconclusive: 2884 group_count: 7 meta: $ref: '#/components/schemas/ResponseMeta' example: request_id: req_cf147349a4134208aebb8c70e25fb7e1 example: data: object: session_breakdown group_by: browser total: sessions: 48210 bots: 3105 humans: 39874 inconclusive: 5231 groups: - value: chrome label: chrome sessions: 21480 bots: 1932 humans: 17201 inconclusive: 2347 other: sessions: 26730 bots: 1173 humans: 22673 inconclusive: 2884 group_count: 7 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 SessionBreakdown: type: object additionalProperties: false required: - object - group_by - total - groups - other - group_count properties: object: type: string enum: - session_breakdown example: session_breakdown group_by: type: string enum: - browser - browser_label - platform - verdict - country - city - asn example: browser total: type: object additionalProperties: false required: - sessions - bots - humans - inconclusive properties: sessions: type: integer minimum: 0 example: 48210 bots: type: integer minimum: 0 example: 3105 humans: type: integer minimum: 0 example: 39874 inconclusive: type: integer minimum: 0 example: 5231 description: Every session the filters match. example: sessions: 48210 bots: 3105 humans: 39874 inconclusive: 5231 groups: type: array items: type: object additionalProperties: false required: - value - label - sessions - bots - humans - inconclusive properties: value: type: string description: >- The group's value, in the form the matching filter parameter accepts. example: chrome label: type: string description: >- Display name: the country name for `country`, the network operator for `asn`, otherwise the value. example: chrome country_code: type: string description: '`city` groups only: the city''s ISO country code.' example: US sessions: type: integer minimum: 0 example: 21480 bots: type: integer minimum: 0 example: 1932 humans: type: integer minimum: 0 example: 17201 inconclusive: type: integer minimum: 0 example: 2347 example: value: chrome label: chrome country_code: US sessions: 21480 bots: 1932 humans: 17201 inconclusive: 2347 example: - value: chrome label: chrome country_code: US sessions: 21480 bots: 1932 humans: 17201 inconclusive: 2347 other: type: object additionalProperties: false required: - sessions - bots - humans - inconclusive properties: sessions: type: integer minimum: 0 example: 26730 bots: type: integer minimum: 0 example: 1173 humans: type: integer minimum: 0 example: 22673 inconclusive: type: integer minimum: 0 example: 2884 description: Sessions in groups beyond `limit`. example: sessions: 26730 bots: 1173 humans: 22673 inconclusive: 2884 group_count: type: integer minimum: 0 description: Distinct groups before `limit` was applied. example: 7 example: object: session_breakdown group_by: browser total: sessions: 48210 bots: 3105 humans: 39874 inconclusive: 5231 groups: - value: chrome label: chrome sessions: 21480 bots: 1932 humans: 17201 inconclusive: 2347 other: sessions: 26730 bots: 1173 humans: 22673 inconclusive: 2884 group_count: 7 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 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 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 ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.