Returns engagement, membership and content-safety figures for one organization over a date range.

The endpoint uses POST because the query is a list of metric objects. It is still a read: sending it again changes nothing. Each retry does count toward the limit of 60 requests an hour, so wait for Retry-After between polls.

Request body

Date range rules:

• The range can be at most 24 months long.
• from cannot be earlier than January, five years ago.
• to cannot be later than the current month.

Breaking any of these returns 400.

Query limit

Padlet runs one query per metric, and one per value when a property is an array (except userType). A request can run at most 50 queries. Split larger requests into several calls.

Metric catalog

How to read the table:

• required: you must send this property. The metric has no all-members total.
• monthly only: you can send userType only together with dimensions: ["month"]. Otherwise the request returns 400. Leaving out both is fine: {"name": "postCount"} returns one number.

Not every property value has a monthly form. For example, memberCount with status: ["active", "inactive"] and dimensions: ["month"] returns a 400 that names the unsupported combination.

userType

userType takes a single role or a list of roles. A list is one combined group, not a split by role. For example, ["teacher", "admin"] returns one figure for teachers and admins together.

Roles depend on the organization type:

The endpoint accepts every role name for every organization type. A role the organization cannot have returns 0, not an error. For example, admin in a classroom returns 0.

all must be sent alone. ["all", "teacher"] returns 400.

Metric notes

• memberCount: status invited and joined also need userType.
• wallEngagementMinutes: with no userType, or with all, the figure includes anonymous visitors. To count members only, list their roles.
• Content-safety metrics (scannedItemCount through moderationCatchRatePercent): available for schools and classrooms only. A team organization gets a 400.

What the figures cover

Membership counts use the organization's current members. A member who has left is not counted, even for a date range before they left.

All other metrics (padlets, posts, comments, reactions, visitors, engagement minutes) count only activity inside the range.

Response

Each metric in attributes.metrics has a name, its properties and its data.

properties shows what Padlet used, not a copy of your request:

• A property you left out comes back as all.
• A single userType comes back as a one-item list.
• Duplicate values are removed.

To match an entry in meta.pending or meta.errors to your request, compare the name and these properties.

Shape of data

Monthly row keys

Each row has a month and one figure. The figure's key depends on the metric:

subscription

• Dates and status show the current billing state, whatever the range.
• Seat count is as of the last day of the range, or today if the range ends in the future.
• Seat count is null if the range covers more than one billing term, or goes back further than the billing history.

Meta

A partial response returns 200, not a 5xx. If every metric failed, metrics is empty. Always check meta.status before reading data.

Errors

Example

curl -X POST https://api.padlet.dev/v1/organizations/$ORG_ID/analytics \
  -H "X-API-KEY: $PADLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": [
      { "name": "padletCount" },
      { "name": "memberCount", "status": "active", "userType": ["teacher", "admin", "owner"] }
    ],
    "dimensions": ["month"]
  }'

{
  "data": {
    "id": "wksp_1oRLGeKoGK9DPvOw",
    "type": "organizationAnalytics",
    "attributes": {
      "metrics": [
        { "name": "padletCount", "properties": { "userType": "all" }, "data": [{ "month": "2026-08", "value": 1 }] },
        {
          "name": "memberCount",
          "properties": { "status": "active", "userType": ["teacher", "admin", "owner"] },
          "data": [{ "month": "2026-08", "value": 1 }]
        }
      ]
    }
  },
  "meta": { "status": "ready", "dateRange": { "from": "2026-08-03", "to": "2027-08-03" } }
}