# Note activity

Count, group, and review note activity across the organization.

Canonical HTML: https://developer.shelfcycle.com/guides/note-activity

Count and rank note activity across the organization, or review the newest matching excerpts for context.

Use note activity when a workflow needs a complete answer across notes, such as all activity this week, touches by author, or the most active customers and products. Use the [Notes guide](/guides/notes) when the workflow has already selected one customer, supplier, or product.

## Endpoint

```text
GET /note-activity
```

Required scope:

```text
notes:read
```

The acting user must also have current ShelfCycle access to view notes. `GET /me` reports `effectiveCapabilities.notes.activityReport` so a workflow can confirm access before offering note-activity actions.

Every request starts with `happenedAtFrom` and `happenedAtTo` calendar days. ShelfCycle interprets those days in the organization's timezone and returns the resolved window in response metadata.

## Count and group activity

Use `view=activity` and choose one `groupBy` value: `day`, `noteType`, `author`, or `subject`.

```bash
curl "$SHELFCYCLE_API_BASE_URL/note-activity?view=activity&groupBy=author&happenedAtFrom=2026-07-13&happenedAtTo=2026-07-19&limit=50" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Weekly activity review"
```

```json
{
  "data": [
    {
      "dimensionKey": "user-id",
      "dimensionLabel": "Jordan Buyer",
      "noteCount": 18
    },
    {
      "dimensionKey": "second-user-id",
      "dimensionLabel": "Taylor Morgan",
      "noteCount": 11
    }
  ],
  "meta": {
    "windowFrom": "2026-07-13T04:00:00.000Z",
    "windowTo": "2026-07-20T04:00:00.000Z",
    "timezone": "America/New_York",
    "totalNotes": 29,
    "limit": 50,
    "hasMore": false,
    "nextCursor": null,
    "warnings": [],
    "generatedAt": "2026-07-19T15:30:00.000Z",
    "view": "activity",
    "groupBy": "author"
  }
}
```

Rows are ranked by note count. `meta.totalNotes` is the exact number of notes in the complete filtered population, independent of the number of grouped rows returned.

Subject groups include `dimensionType` and `dimensionId` when the subject is still available, so a workflow can connect a ranked group to the selected record.

## Narrow the population

Apply any combination of these filters to the initial request:

| Filter | Use it for |
| --- | --- |
| `noteType` | Limit activity to one note type, such as `EMAIL`, `PHONE_MEETING`, `OPPORTUNITY`, or `QUOTE`. |
| `createdById` | Limit activity to one author. |
| `subjectType` | Limit activity to one subject type. |
| `subjectId` | Limit activity to one exact subject. Send `subjectType` with it. |
| `contains` | Match text in note titles or bodies within a date range of up to 366 days. |

For example, count customer-related email notes containing a product name:

```bash
curl "$SHELFCYCLE_API_BASE_URL/note-activity?view=activity&groupBy=subject&happenedAtFrom=2026-04-01&happenedAtTo=2026-06-30&noteType=EMAIL&subjectType=CUSTOMER&contains=acetone" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

## Review recent excerpts

Use `view=list` to receive newest-first matching notes with their activity day, type, title, author, subject, and a short excerpt.

```bash
curl "$SHELFCYCLE_API_BASE_URL/note-activity?view=list&happenedAtFrom=2026-07-13&happenedAtTo=2026-07-19&noteType=PHONE_MEETING&limit=25" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"
```

```json
{
  "data": [
    {
      "id": "note-id",
      "happenedDay": "2026-07-18",
      "noteType": "PHONE_MEETING",
      "title": "Quarterly supply review",
      "author": "Jordan Buyer",
      "subjectType": "CUSTOMER",
      "subjectId": "customer-id",
      "subjectName": "Northstar Chemical",
      "excerpt": "Reviewed the next-quarter forecast and confirmed the follow-up items."
    }
  ],
  "meta": {
    "windowFrom": "2026-07-13T04:00:00.000Z",
    "windowTo": "2026-07-20T04:00:00.000Z",
    "timezone": "America/New_York",
    "totalNotes": 12,
    "limit": 25,
    "hasMore": false,
    "nextCursor": null,
    "warnings": [],
    "generatedAt": "2026-07-19T15:30:00.000Z",
    "view": "list",
    "groupBy": null
  }
}
```

When `meta.hasMore` is true, call the same endpoint with `cursor={nextCursor}` as the only query parameter. The cursor preserves the original filters and date window.

> **Information**: Use grouped activity for complete counts and rankings. Use list view when a workflow needs the matching note excerpts and subjects behind those totals.