Skip to main content
GET
/
forms
/
count
Count Forms
curl --request GET \
  --url https://connect.penbox.io/v1/forms/count \
  --header 'Authorization: Bearer <token>'
{
  "count": 123,
  "by": {}
}
Get the total count of forms matching your filter criteria, with optional grouping by field values.

​
Query Parameters

​
group-by
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)

​
Response Structure

​
Without Grouping

{
  "count": 42
}

​
With Grouping

{
  "count": 42,
  "by": {
    "status": {
      "pending": 15,
      "completed": 20,
      "draft": 7
    }
  }
}
Use the group-by parameter to get distribution statistics for your forms, which is useful for dashboards and analytics.

Authorizations

​
Authorization
string
header
required

API token (starts with pnbx_). Create at https://app.penbox.io/workspace/settings/api. Include as: Authorization: Bearer {token}

Query Parameters

​
workspace[slug]
string

Filter by workspace slug

​
flow[slug]

Filter by flow slug (single value or array)

​
flow[customization]
string<uuid>

Filter by flow customization UUID

​
owner[email]
string<email>

Filter by owner email

​
user[given_name]
string

Filter by user first name

​
user[family_name]
string

Filter by user last name

​
user[email]
string<email>

Filter by user email

​
user[phone]
string

Filter by user phone number

​
archived
boolean
default:false

Filter by archived status

​
active
boolean

Filter by active status

​
completed
boolean

Filter by completed status

​
processed
boolean

Filter by processed status

​
filter
string

Filter using advanced JSON syntax. If specified, will ignore all other filter parameters. See the Advanced Filters guide for more information.

​
group-by
string

Group counts by field (e.g., 'status', 'user.email', 'data.field')

Response

200 - application/json

Successful response

​
count
integer
required

Total number of forms

​
by
object

Grouped counts (only when group-by is specified)