List activity

GET

/api/v1/activity

curl --request GET \
  --url 'https://example.com/api/v1/activity?group=plays' \
  --cookie kivo_session=<kivo_session>

• The server itself, under its configured base path (such as `/kivo`).

Backs the Activity page. What happened on the server, newest first: plays started and finished, root works added, sign-ins and failed ones, users joining, task runs ending and problems raised, kept 90 days. Each event’s fields are nested under its kind’s group: play, added, signIn, joined, task or problem. Names are as they were when it happened. A run of failed sign-ins for one user from one address within the hour is one event, its count and occurredAt the latest. An activityChanged event says there’s more.

Authorizations

• cookieAuth
• bearerAuth

Parameters

Query Parameters

group

The Activity page’s Show filter: plays (playStarted, playFinished), added, signIns (signedIn, signInFailed, userJoined) and server (taskEnded, problemRaised).

string

Allowed values: plays added signIns server

Only these events. Default every one.

after

string

The next cursor from the previous page.

limit

integer

>= 1 <= 200

Page size; 50 by default.

Responses

200

Events.

Media typeapplication/json

object

items

required

Array<object>

One event of the Activity page, its kind’s fields under its group.

object

id

required

A UUIDv7.

string format: uuid

occurredAt

required

string format: date-time

kind

required

What an event tells of. Skip kinds you don’t know.

string

Allowed values: playStarted playFinished added signedIn signInFailed userJoined taskEnded problemRaised

play

playStarted and playFinished: a play started, or ended past the played threshold.

object

userId

required

A UUIDv7.

string format: uuid

username

required

string

work

required

A work as an event names it; an episode by its series, with its season and number.

object

workId

required

A UUIDv7.

string format: uuid

kind

required

What a work is: video an item of a videos library and book an item of an audiobooks library. Skip kinds you don’t know.

string

Allowed values: movie series season episode extra video book

title

required

string

seasonNumber

integer

episodeNumber

integer

clientName

The name of the session or API key it was played on.

string

local

required

boolean

added

added: a folder’s new files, after a scan, under the root work of the first: a series’ episodes, a movie, a book or videos.

object

libraryName

required

The library’s name.

string

work

required

A work as an event names it; an episode by its series, with its season and number.

object

workId

required

A UUIDv7.

string format: uuid

kind

required

What a work is: video an item of a videos library and book an item of an audiobooks library. Skip kinds you don’t know.

string

Allowed values: movie series season episode extra video book

title

required

string

seasonNumber

integer

episodeNumber

integer

count

required

Files added, extras aside.

integer

signIn

signedIn and signInFailed. A failed sign-in for a username nobody has names no user.

object

userId

A UUIDv7.

string format: uuid

username

string

clientName

The new session’s name.

string

address

required

The client’s address.

string

local

required

boolean

count

signInFailed: the failed sign-ins it tells of.

integer

joined

userJoined: a user created from an invite, or by an admin.

object

userId

required

A UUIDv7.

string format: uuid

username

required

string

addedBy

The admin who added the user; absent for an invite.

string

task

taskEnded: a night run’s end, or Run now’s, that did something or failed.

object

task

required

A task’s name. Skip tasks you don’t know.

string

Allowed values: scan-libraries prune-gone-files refresh-metadata prune-provider-cache make-previews prune-previews find-markers prune-markers extract-subtitles prune-subtitles prepare-downloads prune-downloads library-changes prune-activity make-backup optimize-database

summary

string

error

Why the run failed.

string

failedCount

required

The task’s items that failed for good, as it ended.

integer

problem

problemRaised: a problem as it was raised.

object

id

required

The problem’s ID, as GET /api/v1/problems names it.

string

code

required

string

message

required

string

severity

required

How much a server problem matters.

string

Allowed values: info warning error

next

string

Example

{
  "items": [
    {
      "kind": "playStarted",
      "play": {
        "work": {
          "kind": "movie"
        }
      },
      "added": {
        "work": {
          "kind": "movie"
        }
      },
      "task": {
        "task": "scan-libraries"
      },
      "problem": {
        "severity": "info"
      }
    }
  ]
}

400

The request is malformed or a field is invalid (code invalidRequest).

Media typeapplication/problem+json

An RFC 9457 problem document. code is stable and is what clients translate.

object

type

required

A URI naming the problem type; about:blank when only code matters.

string

title

required

A short English summary, for logs.

string

status

required

integer

detail

English detail for logs and developers; never internal error text.

string

instance

string

code

required

A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.

string

Allowed values: invalidRequest unauthenticated invalidCredentials wrongPassword forbidden crossOrigin denied notFound expired notReady rangeNotSatisfiable conflict alreadySetUp nameTaken lastAdmin ownUser fileStillPresent kindMismatch notStoppable streamLimit notPlayable noFallback playEnded throttled rateLimited providerUnavailable notConfigured quotaUsed transcodeBusy transcodeFailed internal

requestId

required

The request ID, also in the X-Request-Id header and the server log.

string

reason

For transcodeBusy and notPlayable, why. For transcodeBusy: transcodeLimit or storageFull. For notPlayable: noTracks, fileUnplayable, subtitleUnplayable, transcodeFailed, keyframeIndexMissing or downloadsNotAllowed.

string

Allowed values: noTracks fileUnplayable subtitleUnplayable keyframeIndexMissing transcodeFailed transcodeLimit storageFull downloadsNotAllowed sourceUnreadable subtitlesUnavailable planUnreadable

mismatch

For fileUnplayable, the capability the file failed.

object

field

required

string

declared

The declared value, lists joined by commas; absent when the client declared none.

string

actual

required

string

retryAfterSeconds

For throttled and rateLimited, the Retry-After header’s value.

integer

errors

For invalidRequest, what’s wrong with which field.

Array<object>

object

field

required

A JSON pointer into the body, or a parameter name.

string

code

required

What’s wrong with a field: tooLarge for a file or list over its size, unsupported for a file in a format the server doesn’t take, unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list for the series, and notABook for a work edited with books that isn’t one.

string

Allowed values: required invalid tooShort tooLong tooLarge unsupported outOfRange unknownEpisodeGroup notABook

plays

For streamLimit, the user’s plays, to show what is playing where.

Array<object>

One of the user’s plays, for the stream limit.

object

id

required

A UUIDv7.

string format: uuid

workId

required

A UUIDv7.

string format: uuid

title

required

string

clientName

The name of the session or API key it was started by.

string

startedAt

required

string format: date-time

message

For playEnded, the admin’s words to the viewer, when they gave any.

string

resetsAt

For quotaUsed, when the quota resets, when the provider said.

string format: date-time

Example

{
  "code": "invalidRequest",
  "reason": "noTracks",
  "errors": [
    {
      "code": "required"
    }
  ]
}

401

No valid session or API key (code unauthenticated), or a failed sign-in (code invalidCredentials).

Media typeapplication/problem+json

An RFC 9457 problem document. code is stable and is what clients translate.

object

type

required

A URI naming the problem type; about:blank when only code matters.

string

title

required

A short English summary, for logs.

string

status

required

integer

detail

English detail for logs and developers; never internal error text.

string

instance

string

code

required

A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.

string

Allowed values: invalidRequest unauthenticated invalidCredentials wrongPassword forbidden crossOrigin denied notFound expired notReady rangeNotSatisfiable conflict alreadySetUp nameTaken lastAdmin ownUser fileStillPresent kindMismatch notStoppable streamLimit notPlayable noFallback playEnded throttled rateLimited providerUnavailable notConfigured quotaUsed transcodeBusy transcodeFailed internal

requestId

required

The request ID, also in the X-Request-Id header and the server log.

string

reason

For transcodeBusy and notPlayable, why. For transcodeBusy: transcodeLimit or storageFull. For notPlayable: noTracks, fileUnplayable, subtitleUnplayable, transcodeFailed, keyframeIndexMissing or downloadsNotAllowed.

string

Allowed values: noTracks fileUnplayable subtitleUnplayable keyframeIndexMissing transcodeFailed transcodeLimit storageFull downloadsNotAllowed sourceUnreadable subtitlesUnavailable planUnreadable

mismatch

For fileUnplayable, the capability the file failed.

object

field

required

string

declared

The declared value, lists joined by commas; absent when the client declared none.

string

actual

required

string

retryAfterSeconds

For throttled and rateLimited, the Retry-After header’s value.

integer

errors

For invalidRequest, what’s wrong with which field.

Array<object>

object

field

required

A JSON pointer into the body, or a parameter name.

string

code

required

What’s wrong with a field: tooLarge for a file or list over its size, unsupported for a file in a format the server doesn’t take, unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list for the series, and notABook for a work edited with books that isn’t one.

string

Allowed values: required invalid tooShort tooLong tooLarge unsupported outOfRange unknownEpisodeGroup notABook

plays

For streamLimit, the user’s plays, to show what is playing where.

Array<object>

One of the user’s plays, for the stream limit.

object

id

required

A UUIDv7.

string format: uuid

workId

required

A UUIDv7.

string format: uuid

title

required

string

clientName

The name of the session or API key it was started by.

string

startedAt

required

string format: date-time

message

For playEnded, the admin’s words to the viewer, when they gave any.

string

resetsAt

For quotaUsed, when the quota resets, when the provider said.

string format: date-time

Example

{
  "code": "invalidRequest",
  "reason": "noTracks",
  "errors": [
    {
      "code": "required"
    }
  ]
}

403

Signed in, but this needs an admin (code forbidden); a same-origin request (code crossOrigin); or a device code that was denied (code denied).

Media typeapplication/problem+json

An RFC 9457 problem document. code is stable and is what clients translate.

object

type

required

A URI naming the problem type; about:blank when only code matters.

string

title

required

A short English summary, for logs.

string

status

required

integer

detail

English detail for logs and developers; never internal error text.

string

instance

string

code

required

A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.

string

Allowed values: invalidRequest unauthenticated invalidCredentials wrongPassword forbidden crossOrigin denied notFound expired notReady rangeNotSatisfiable conflict alreadySetUp nameTaken lastAdmin ownUser fileStillPresent kindMismatch notStoppable streamLimit notPlayable noFallback playEnded throttled rateLimited providerUnavailable notConfigured quotaUsed transcodeBusy transcodeFailed internal

requestId

required

The request ID, also in the X-Request-Id header and the server log.

string

reason

For transcodeBusy and notPlayable, why. For transcodeBusy: transcodeLimit or storageFull. For notPlayable: noTracks, fileUnplayable, subtitleUnplayable, transcodeFailed, keyframeIndexMissing or downloadsNotAllowed.

string

Allowed values: noTracks fileUnplayable subtitleUnplayable keyframeIndexMissing transcodeFailed transcodeLimit storageFull downloadsNotAllowed sourceUnreadable subtitlesUnavailable planUnreadable

mismatch

For fileUnplayable, the capability the file failed.

object

field

required

string

declared

The declared value, lists joined by commas; absent when the client declared none.

string

actual

required

string

retryAfterSeconds

For throttled and rateLimited, the Retry-After header’s value.

integer

errors

For invalidRequest, what’s wrong with which field.

Array<object>

object

field

required

A JSON pointer into the body, or a parameter name.

string

code

required

What’s wrong with a field: tooLarge for a file or list over its size, unsupported for a file in a format the server doesn’t take, unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list for the series, and notABook for a work edited with books that isn’t one.

string

Allowed values: required invalid tooShort tooLong tooLarge unsupported outOfRange unknownEpisodeGroup notABook

plays

For streamLimit, the user’s plays, to show what is playing where.

Array<object>

One of the user’s plays, for the stream limit.

object

id

required

A UUIDv7.

string format: uuid

workId

required

A UUIDv7.

string format: uuid

title

required

string

clientName

The name of the session or API key it was started by.

string

startedAt

required

string format: date-time

message

For playEnded, the admin’s words to the viewer, when they gave any.

string

resetsAt

For quotaUsed, when the quota resets, when the provider said.

string format: date-time

Example

{
  "code": "invalidRequest",
  "reason": "noTracks",
  "errors": [
    {
      "code": "required"
    }
  ]
}

default

A server-side failure: 500 (code internal, or transcodeFailed for a play’s media), or 503 for something unavailable (codes providerUnavailable and transcodeBusy, for now; notConfigured, until an admin configures it).

Media typeapplication/problem+json

An RFC 9457 problem document. code is stable and is what clients translate.

object

type

required

A URI naming the problem type; about:blank when only code matters.

string

title

required

A short English summary, for logs.

string

status

required

integer

detail

English detail for logs and developers; never internal error text.

string

instance

string

code

required

A problem’s stable code, which clients translate. A client that doesn’t know a code goes by the response’s status.

string

Allowed values: invalidRequest unauthenticated invalidCredentials wrongPassword forbidden crossOrigin denied notFound expired notReady rangeNotSatisfiable conflict alreadySetUp nameTaken lastAdmin ownUser fileStillPresent kindMismatch notStoppable streamLimit notPlayable noFallback playEnded throttled rateLimited providerUnavailable notConfigured quotaUsed transcodeBusy transcodeFailed internal

requestId

required

The request ID, also in the X-Request-Id header and the server log.

string

reason

For transcodeBusy and notPlayable, why. For transcodeBusy: transcodeLimit or storageFull. For notPlayable: noTracks, fileUnplayable, subtitleUnplayable, transcodeFailed, keyframeIndexMissing or downloadsNotAllowed.

string

Allowed values: noTracks fileUnplayable subtitleUnplayable keyframeIndexMissing transcodeFailed transcodeLimit storageFull downloadsNotAllowed sourceUnreadable subtitlesUnavailable planUnreadable

mismatch

For fileUnplayable, the capability the file failed.

object

field

required

string

declared

The declared value, lists joined by commas; absent when the client declared none.

string

actual

required

string

retryAfterSeconds

For throttled and rateLimited, the Retry-After header’s value.

integer

errors

For invalidRequest, what’s wrong with which field.

Array<object>

object

field

required

A JSON pointer into the body, or a parameter name.

string

code

required

What’s wrong with a field: tooLarge for a file or list over its size, unsupported for a file in a format the server doesn’t take, unknownEpisodeGroup for a group:<ID> ordering TMDb doesn’t list for the series, and notABook for a work edited with books that isn’t one.

string

Allowed values: required invalid tooShort tooLong tooLarge unsupported outOfRange unknownEpisodeGroup notABook

plays

For streamLimit, the user’s plays, to show what is playing where.

Array<object>

One of the user’s plays, for the stream limit.

object

id

required

A UUIDv7.

string format: uuid

workId

required

A UUIDv7.

string format: uuid

title

required

string

clientName

The name of the session or API key it was started by.

string

startedAt

required

string format: date-time

message

For playEnded, the admin’s words to the viewer, when they gave any.

string

resetsAt

For quotaUsed, when the quota resets, when the provider said.

string format: date-time

Example

{
  "code": "invalidRequest",
  "reason": "noTracks",
  "errors": [
    {
      "code": "required"
    }
  ]
}