Reads engagement, membership and content-safety analytics for one organization over a period. The query is a structured array of metric objects, so this endpoint uses POST. It is still a safe, idempotent read, so a retry changes nothing. A retry does spend one of the hour's 60 requests, so wait for Retry-After rather than polling in a tight loop.

Request body

Omitting from and to reads the organization's current billing term, or all time if it has none.

from cannot precede January of five years ago, and to cannot be later than the current month. A range inside the 24-month cap but outside that window is still a 400.

Metric catalog

userType takes organization roles, and which roles an organization has depends on its type:

The endpoint accepts any of these role names for any organization. It does not reject roles that organization type cannot have. Asking a classroom for admin returns a truthful zero, not an error. Send the roles the organization actually uses.

all must be sent alone. Mixed with role names — ["all", "teacher"] — it is read as a role and the request is a 400.

wallEngagementMinutes without userType, or with userType: all, covers the whole workspace. That includes anonymous visitors, not just members. Send an explicit role list to exclude them.

The six content-safety metrics run from scannedItemCount through moderationCatchRatePercent. They need content safety, and only schools and classrooms have it. Asking for them on a team organization returns a 400, not a misleading zero.

memberCount with status invited or joined has no all-members form, so those two require userType.

"Monthly only" means a metric's role-sliced form exists only as a monthly series. If you send userType for one of these metrics, you must also send dimensions: ["month"], or the request is a 400. Sending neither is fine: {"name": "postCount"} alone is a valid request and returns a single number. "Required" means the metric has no all-members form at all.

Responses carry the resolved properties, not a copy of the request. An omitted property comes back as all. A scalar userType comes back as a one-element array. Duplicates are collapsed. Match a meta.pending or meta.errors entry to your request using the name plus those resolved properties.

Membership counts describe the organization's current roster, not a historical snapshot. A member who has since left is excluded, even from a range that predates their departure. status: all and joined count current members who joined on or before to. status: active counts current members who contributed anything between from and to. status: inactive is the current roster size minus that active count. status: invited ignores from and to altogether. It counts the invitations outstanding right now. Everything else (posts, padlets, comments, reactions, visitors, engagement minutes) is scoped to the range.

What data holds

The shape follows the request:

subscription is the one metric whose fields are not a figure for the range. The dates and status describe the organization's current billing state. The seat count is as of the last day of the range, or today when the range ends in the future, which the default range usually does. It comes back null when the range spans more than one billing term, or when billing history doesn't reach that far back.

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" } }
}

Not every metric has a monthly form for every slice: memberCount has one for active with a role slice, so asking for ["active", "inactive"] alongside dimensions: ["month"] is a 400 naming the combination.