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

# Count Forms

> Get the total count of forms matching filter criteria, with optional grouping.

Get the total count of forms matching your filter criteria, with optional grouping by field values.

## Query Parameters

<ParamField query="group-by" type="string">
  Group counts by a specific field. Supported values:

  * `status` - Group by form status
  * `user.{field}` - Group by user field (e.g., `user.email`)
  * `data.{field}` - Group by data field (e.g., `data.property_type`)
</ParamField>

## Response Structure

### Without Grouping

```json theme={null}
{
  "count": 42
}
```

### With Grouping

```json theme={null}
{
  "count": 42,
  "by": {
    "status": {
      "pending": 15,
      "completed": 20,
      "draft": 7
    }
  }
}
```

<Tip>
  Use the `group-by` parameter to get distribution statistics for your forms, which is useful for dashboards and analytics.
</Tip>


## OpenAPI

````yaml GET /forms/count
openapi: 3.0.0
info:
  title: Penbox API
  version: '1.0'
  description: >-
    The Penbox API provides programmatic access to Penbox's form management,
    case management, and document processing capabilities. Authenticate using
    Bearer tokens created at https://app.penbox.io/workspace/settings/api
servers:
  - url: https://connect.penbox.io/v1
    description: Production
  - url: https://connect.aiboov.com/v1
    description: Staging
security:
  - BearerAuth: []
paths:
  /forms/count:
    get:
      summary: Count Forms
      description: >-
        Get the total count of forms matching filter criteria, with optional
        grouping.
      operationId: count-forms
      parameters:
        - $ref: '#/components/parameters/FormWorkspaceSlug'
        - $ref: '#/components/parameters/FormFlowSlug'
        - $ref: '#/components/parameters/FormFlowCustomization'
        - $ref: '#/components/parameters/OwnerEmail'
        - $ref: '#/components/parameters/FormUserGivenName'
        - $ref: '#/components/parameters/FormUserFamilyName'
        - $ref: '#/components/parameters/FormUserEmail'
        - $ref: '#/components/parameters/FormUserPhone'
        - $ref: '#/components/parameters/Archived'
        - $ref: '#/components/parameters/FormActive'
        - $ref: '#/components/parameters/FormCompleted'
        - $ref: '#/components/parameters/FormProcessed'
        - $ref: '#/components/parameters/AdvancedFilter'
        - name: group-by
          in: query
          description: Group counts by field (e.g., 'status', 'user.email', 'data.field')
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: Total number of forms
                  by:
                    type: object
                    description: Grouped counts (only when group-by is specified)
                    additionalProperties:
                      type: object
                      additionalProperties:
                        type: integer
                required:
                  - count
components:
  parameters:
    FormWorkspaceSlug:
      name: workspace[slug]
      in: query
      description: Filter by workspace slug
      schema:
        type: string
    FormFlowSlug:
      name: flow[slug]
      in: query
      description: Filter by flow slug (single value or array)
      schema:
        oneOf:
          - type: string
          - type: array
            items:
              type: string
    FormFlowCustomization:
      name: flow[customization]
      in: query
      description: Filter by flow customization UUID
      schema:
        type: string
        format: uuid
    OwnerEmail:
      name: owner[email]
      in: query
      description: Filter by owner email
      schema:
        type: string
        format: email
    FormUserGivenName:
      name: user[given_name]
      in: query
      description: Filter by user first name
      schema:
        type: string
    FormUserFamilyName:
      name: user[family_name]
      in: query
      description: Filter by user last name
      schema:
        type: string
    FormUserEmail:
      name: user[email]
      in: query
      description: Filter by user email
      schema:
        type: string
        format: email
    FormUserPhone:
      name: user[phone]
      in: query
      description: Filter by user phone number
      schema:
        type: string
    Archived:
      name: archived
      in: query
      description: Filter by archived status
      schema:
        type: boolean
        default: false
    FormActive:
      name: active
      in: query
      description: Filter by active status
      schema:
        type: boolean
    FormCompleted:
      name: completed
      in: query
      description: Filter by completed status
      schema:
        type: boolean
    FormProcessed:
      name: processed
      in: query
      description: Filter by processed status
      schema:
        type: boolean
    AdvancedFilter:
      name: filter
      in: query
      description: >-
        Filter using advanced JSON syntax. If specified, will ignore all other
        filter parameters. See the [Advanced
        Filters](/api-reference/advanced-filters) guide for more information.
      schema:
        type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
      description: >-
        API token (starts with pnbx_). Create at
        https://app.penbox.io/workspace/settings/api. Include as: Authorization:
        Bearer {token}

````