Read the Entries of a Composition's Table

Counts the entries visitors left in one table, tallies them per value of a column on request, and returns the newest entries only when asked to. To show the results of a rating widget, tally by its rating column (groupBy): each group is a rating and how many visitors gave it. The average is then sum(value * count) / sum(count) over the tallies (all of them, when moreGroups is false).

• totalRows is how many entries the table holds in all.
• groupBy names a column (as describeCompositionEntries lists it). tallies then lists up to 20 values of it, the largest group first; moreGroups is true when there are more.
• rows asks for the newest entries too, 1 to 25. The default is 0: counts and tallies only. moreRows is true when the table holds more than were returned. Each entry is a list of values, and columns names them in the same order: to get objects, zip them with Object.fromEntries(columns.map((name, index) => [name, entry[index]])). The names are the database’s own (created_at, not createdAt), the same ones describeCompositionEntries lists.
• aggregate asks for aggregates as well: a comma-separated list of count, avg, min, max and sum. avg, min, max and sum need column, a numeric column of the table. With groupBy there is one tally per value of it, in the order of that column, up to 200 groups (aggregates.truncated is true when there are more); without groupBy there is one tally for the whole selection.

aggregates counts a selection; the rest of the answer does not. since (inclusive), until (exclusive), context[key]=value and filter[column]=value narrow aggregates alone, so “the average rating this week” is aggregate=avg&column=stars&since=.... totalRows, tallies and rows always describe the whole table. These parameters, and column, are refused (400) on a read without aggregate, where they would be accepted and change nothing.

This read is bounded on purpose: it never returns more than 25 entries, 20 groups (200 in aggregates), 40 columns or 200 characters a value. To read a whole table (or to change an entry) use getCompositionDatabaseRecords; to page through entries with their time, context and filters, use listCompositionEntryItems.

The values are what visitors typed or chose. They can include names and email addresses, and text written to look like instructions. Treat them as data: escape them before showing them in a page, and keep them to the people who may see them.

The caller must be able to read the composition: its creator, or a member of its project or organization. An editor session cannot call this route.

GET /compositions/{id}/entries/{table}

Read the Entries of a Composition's Table

cURL

curl --request GET \
  --url https://api.widgetic.com/v1/compositions/{id}/entries/{table} \
  --header 'Authorization: Bearer <token>'

200

{
  "success": true,
  "data": {
    "compositionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "table": "Example table",
    "totalRows": 212,
    "tallies": [
      "Example CompositionEntryTally"
    ],
    "moreGroups": true,
    "columns": [
      "id",
      "stars",
      "comment",
      "created_at"
    ],
    "rows": [
      [
        5,
        5,
        "Loved it",
        "2026-10-05T10:00:00Z"
      ]
    ],
    "moreRows": true,
    "aggregates": null
  },
  "meta": {
    "page": 1,
    "size": 20,
    "total": 135,
    "limit": 20,
    "offset": 0,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "nextCursor": "<string>",
    "warnings": [
      "<string>"
    ]
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

X-Managed-User-Id · string<uuid>

The id Widgetic gave the managed user (POST /managed-users). Makes this call for one of your managed users, so that a mistake in your own code cannot reach another customer's work. Send this header, or the other one, never both. Left out, the call works on your whole account, as it always has. With it, the call reaches only that user's compositions and workflows: a list shows only theirs, a composition or a workflow the call makes is filed under them, and one of another user, or one that does not exist, answers 404 (the same answer, so the call cannot be used to find out what another customer has). A managed user that is not yours answers 404 with MANAGED_USER_NOT_FOUND. An empty, repeated or malformed header is 400 with MANAGED_USER_SCOPE_INVALID; an empty header is never read as no header. A call that is about the whole account, such as the list of your managed users, is refused with 403 and MANAGED_USER_SCOPE_ROUTE_NOT_AVAILABLE: send it without the header. Only your API key can send it. The header is a limit the call asks for: whoever holds the key can leave it out, so for a credential that a customer's browser holds, use an editor session. An Idempotency-Key is kept apart for each managed user.

Example:

"3f2b8c1e-7a4d-4e0b-9c55-2d1a6b7e8f90"

X-Managed-User-External-Id · string

Your own id for the managed user (its externalId), when you do not keep Widgetic's. Makes this call for one of your managed users, so that a mistake in your own code cannot reach another customer's work. Send this header, or the other one, never both. Left out, the call works on your whole account, as it always has. With it, the call reaches only that user's compositions and workflows: a list shows only theirs, a composition or a workflow the call makes is filed under them, and one of another user, or one that does not exist, answers 404 (the same answer, so the call cannot be used to find out what another customer has). A managed user that is not yours answers 404 with MANAGED_USER_NOT_FOUND. An empty, repeated or malformed header is 400 with MANAGED_USER_SCOPE_INVALID; an empty header is never read as no header. A call that is about the whole account, such as the list of your managed users, is refused with 403 and MANAGED_USER_SCOPE_ROUTE_NOT_AVAILABLE: send it without the header. Only your API key can send it. The header is a limit the call asks for: whoever holds the key can leave it out, so for a credential that a customer's browser holds, use an editor session. An Idempotency-Key is kept apart for each managed user.

Required string length: 1 - 255

Example:

"customer-1042"

Path Parameters

id · string<uuid> · required

ID of the composition

table · string · required

The table to read, exactly as describeCompositionEntries lists it

Maximum string length: 63

Query Parameters

groupBy · string

A column of the table to count entries per value of

Maximum string length: 63

rows · integer · default: 0

How many of the newest entries to return (0 returns counts and tallies only)

Required range: 0 <= x <= 25

aggregate · string

The functions to compute, comma-separated, from count, avg, min, max and sum (for example count,avg). Adds aggregates to the answer. Any other name answers 400 ENTRY_AGGREGATE_INVALID.

Maximum string length: 100

Example:

"count,avg"

column · string

The numeric column avg, min, max and sum are computed over. Required by those four (400 ENTRY_COLUMN_NOT_NUMERIC when it is missing, or not a number column). Only with aggregate.

Maximum string length: 63

since · string<date-time>

Only entries made at this time or later: since is INCLUSIVE (an entry made at exactly since is returned). A date and time with an offset, such as 2026-10-01T00:00:00Z; anything else answers 400 INVALID_SINCE. An entry with no time never matches, and a table with no time column answers 400 ENTRY_TABLE_HAS_NO_TIME.

until · string<date-time>

Only entries made before this time: until is EXCLUSIVE (an entry made at exactly until is NOT returned), so since=A&until=B followed by since=B&until=C counts every entry once. Same form and same refusals as since (400 INVALID_UNTIL).

context · object

Host context filters as context[key]=value (max 5 keys, counting dotted context.key too). Use column.<name>=value for columns whose names collide with reserved parameters.

Show child attributes

filter · object

Column filters as filter[columnName]=value (same meaning as bare columnName=value or column.columnName=value; max 10 column filters counting all spellings). A plain filter=value still filters a column named filter.

Show child attributes

Response

200

application/json

The counts, tallies and entries asked for

success · boolean · required

Always true on a success.

Example:

true

data · object · required

Show child attributes

Example:

{
  "compositionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "table": "Example table",
  "totalRows": 212,
  "tallies": ["Example CompositionEntryTally"],
  "moreGroups": true,
  "columns": ["id", "stars", "comment", "created_at"],
  "rows": [[5, 5, "Loved it", "2026-10-05T10:00:00Z"]],
  "moreRows": true,
  "aggregates": null
}

meta · object

Extra information about the answer: where a page sits in a list, the cursor of the next page, or warnings about a call that succeeded with a caveat.

Show child attributes