Skip to main content
An activity log entry records one action in your organization. It says who took it (actor), what it touched (targets), what kind of action it was (event_type), and how it ended (outcome). An admin who changes a user’s Lumos roles, and a user who disconnects an app, each produce an entry. The log is read-only. You read it through one endpoint, List Activity Logs.
The Activity Log object

​
Attributes

​
Actors and targets

actor, and each item in targets, has a type field (actor_type or target_type) and the fields of the thing it names. A Lumos user has email, given_name, and family_name. An app class has app_id and name. The fields depend on the type, so read the type before you read the rest. When Lumos can’t find the underlying record, only the type is present.

​
Who can read the log

Of the built-in roles, Admin and Read Only Admin can read the whole log. Auditor and AppStore Read Only Admin can read their own product area’s entries by sending product_area=ACCESS_REVIEW or product_area=APP_STORE. Without product_area, or with an area your role can’t read, the call returns 403. Migrate activity logs and identity events covers what this means for these roles. product_area limits the list to one product area’s entries: APP_STORE, ACCESS_REVIEW, VENDORS, or OTHER. When you send product_area, entries that belong to no product area don’t appear.

​
The time window

since and until bound the list, and both are inclusive. Lumos reads either one without a UTC offset as UTC. If you omit them, the window is the last seven days, and Lumos recomputes it on every request. That default is fine for a single page. When you read several pages, send both since and until so that the set of entries doesn’t change between pages. A page token continues only the sequence of pages it came from, so send the same since and until with it. The window selects entries by when their action finished. Lumos sorts the list by event_began_at, newest first, so an entry can have an event_began_at earlier than since.

​
Reading the log from a log shipper

To poll List Activity Logs from a log shipper such as Elastic Filebeat’s httpjson input or Cribl, follow these steps. They read the log in time windows and page through each one:
  1. Poll in windows with explicit since and until.
  2. For each page, send the previous response’s next_page_token as page_token, with the same since and until.
  3. Stop when next_page_token is missing or null.
  4. Start each window 5 minutes before the previous until, so consecutive windows overlap.
  5. Drop entries whose event_hash you’ve already seen.
page_size can be up to 100. The overlap and the deduplication cover two cases. Both ends of a window are inclusive, so an entry that finished exactly on a boundary appears in two windows. Deduplication drops the second copy. An entry can appear 30 seconds to several minutes after its action finishes, so it can arrive after you’ve read its window. The overlap lets the next window read it. Filebeat. In the httpjson input, response.split with a target of body.activity_logs makes each entry its own Filebeat event. response.pagination can set the url.params.page_token target from the last response’s next_page_token, and request.transforms can set the Authorization header. Cribl. A REST Collector’s Response Body Attribute pagination reads the next page’s position from an attribute of the response body, here next_page_token. Check how your REST Collector sends that value on the next request. Lumos reads the page token only from the page_token query parameter. A page token sent under another name returns 400.

​
Endpoints