Read a library's events

Recipes for specific tasks against the API.

Show what a user did in their library, filter it by series, event type or date, and poll for new events without missing any.

The events feed, GET /v2/my/library/events, returns an event each time a series is added or removed, or its reading state, rating or progress changes, newest first. Other fields, such as notes, dates and lists, have no events yet: what is recorded.

Tip

Keeping a copy of the user's library in sync? Use the changes feed. It has every field, sends removals, and is the endpoint built for sync. The events feed is for showing what happened.

Warning

This endpoint is internal. It serves our own event log as it is stored, so event types, fields and their meaning can change at any time, without notice. Build on it only if you can absorb that.

Access#↑

Use an OAuth token with the library.read scope, sent as Authorization: Bearer. For your own library, a personal access token sent as x-api-key works too.

1. Read the newest events#↑

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://api.mangabaka.org/v2/my/library/events?limit=50"
{
	"status": 200,
	"pagination": {
		"limit": 50,
		"cursor": "eyJ2IjoxLCJtb2RlIjoid2Fsay...",
		"more": true
	},
	"data": [
		{
			"id": 9184211,
			"series_id": 920,
			"event_type": "progress_update",
			"old": { "progress_chapter": 10, "progress_volume": null },
			"new": { "progress_chapter": 14, "progress_volume": null },
			"created_at": "2026-11-05T21:13:44.055Z"
		}
	]
}

Events have no titles or covers. Look up the series_ids with batch series lookup and cache them. A series missing from the lookup was merged or deleted: see follow merged series.

Skip events whose event_type you don't know and keep going. New types will be added.

2. Go further back#↑

While more is true, send pagination.cursor back to get older events:

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://api.mangabaka.org/v2/my/library/events?limit=50&cursor=CURSOR"

more: false means you reached the oldest event.

3. Filter#↑

series_id and event_type can repeat, and all filters combine:

Parameter Keeps
series_id Events for these series
event_type These event types
created_at_lower, created_at_upper Events in this time range, both ends included. UTC in whole seconds, such as 2026-10-01T00:00:00Z.

Rating and state changes for two series in October:

curl -G -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://api.mangabaka.org/v2/my/library/events" \
  -d series_id=920 -d series_id=3391 \
  -d event_type=rating_change -d event_type=state_change \
  -d created_at_lower=2026-10-01T00:00:00Z \
  -d created_at_upper=2026-10-31T23:59:59Z

Send the same filters with every cursor. A cursor sent with different filters returns 400: start again without one.

Filtering by event_type also keeps you clear of types added later.

4. Poll for new events#↑

Page until more is false. That last cursor now returns events that happened after you started reading:

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://api.mangabaka.org/v2/my/library/events?cursor=LAST_CURSOR"
  • Only the last page's cursor polls. A cursor from earlier pages keeps going back in time, even days later, and polling starts once you reach the end.
  • Polled events come roughly oldest first. While more is true, keep paging.
  • Nothing new is 200 with empty data and more: false.
  • Each poll returns a new cursor. Store it once you have saved the page.
  • Save events by id, replacing what you have. The same event can arrive twice, and an event can come back with a new series_id when the user moved it to another series.
  • Nothing is missed if the user changes their library while you read: those changes arrive on your first poll. That includes events dated before where your walk had reached, such as a long import that committed late, or older events re-sent because the user moved an entry to another series.

Only new events#↑

To skip the history, start with start=now. It returns no events and a cursor to poll with:

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://api.mangabaka.org/v2/my/library/events?start=now"

Nothing that happens after this call is missed, including changes already in progress. The first poll can also include a few events from just before the call. For recent history plus new events, walk with created_at_lower instead, so the walk ends sooner.

How often#↑

Poll at most every 15 minutes in the background. Empty polls count against your rate limit.

Errors#↑

Response What to do
400 on a cursor The cursor is invalid or its filters changed. Start again.
Any other 400 Fix the request, such as a range whose lower end is later.
401 or 403 Refresh the token, or ask the user to authorize again.
429 or 5xx Keep your cursor and retry later.

Personal data#↑

Events show when a user read what, including series they removed. Keep them out of shared caches and public logs, and delete them with the rest of a user's data.