Skip to main content

Get all dashboards folders

GET 
/perses-public/api/v1/projects

Returns every folder in the account, sorted by name. Each entry pairs the folder with its dashboards.

The dashboards array is filled only when the withDashboards query parameter is present; otherwise it is always empty. The parameter works by presence, so ?withDashboards=false fills it just as ?withDashboards does.

Calling this endpoint creates the account's root folder if it doesn't exist yet.

Request​

Query Parameters

    withDashboards string

    Include each folder's dashboards. Any value, including an empty one, turns this on.

Responses​

The account's folders.

Schema
  • Array [
    • project object

    A dashboard folder. Carries the Perses project document in doc, wrapped in the fields Logz.io stores alongside it.

    id string

    The folder's identifier, and the only way to address it.

    name string

    The folder's name. Set from metadata.name when the folder is created, and replaced by spec.display.name on an update or by newProjectName on a rename.

    doc object

    A Perses project document. This is the request body for creating and updating a dashboard folder.

    kind stringrequired

    Possible values: [Project]

    metadata objectrequired
    name stringrequired

    The folder's identity. Required, must be non-empty, and has to be unique within the account.

    spec objectrequired
    display objectrequired

    How the folder is labelled in the app. Required on both create and update.

    name stringrequired

    The name shown in the app. Required, and must be non-empty. On an update it also becomes the folder's name.

    description string
    entityId integer

    Internal handle for the account that owns the folder.

    createdBy integer

    Numeric id of the principal that created the folder. For a folder created through this API this is the id of the API token, not of a user.

    updatedBy integer
    createdAt date-time
    updatedAt date-time
    isDeleted boolean

    Returned as true or false by create, update and rename, and as 1 or 0 by the list, get and search endpoints.

    deletedAt date-time

    Null unless the folder was deleted.

    deletedBy integer

    Null unless the folder was deleted.

    dashboards object[]

    The folder's dashboards. Empty in Get all dashboard folders unless withDashboards is present, and limited to the matching dashboards in Search dashboard folders.

  • Array [
    • uid string

    The dashboard's stable identifier. It survives updates and moves, and every endpoint addresses a dashboard by this value. This is the one to store.

    id string

    Identifier of the version row holding the current revision. A new value is issued on every update, and it can't be used to address the dashboard. A dashboard that has never been updated has the same value here as in uid, which makes the two easy to confuse.

    name string

    Internal marker for the dashboard, equal to uid for dashboards created through this API. The name shown in the app is doc.spec.display.name, and the name that search matches is doc.metadata.name.

    projectId string

    The id of the folder holding the dashboard.

    doc object

    A Perses dashboard document. Only metadata.name is validated by Logz.io; spec is stored as sent and has to be a valid Perses dashboard spec for the dashboard to render in the app.

    kind stringrequired

    Possible values: [Dashboard]

    metadata objectrequired
    name stringrequired

    The dashboard's identity, and the only field both search endpoints match on. Required on create and update.

    project string

    Set by the server from the folder in the request path. Any value sent here is replaced.

    tags string[]
    spec objectrequired

    Extra properties are allowed. The Perses dashboard spec. See the Perses dashboard specification for the panel, layout and query plugin shapes.

    display object

    How the dashboard is labelled in the app.

    name string
    description string
    duration string

    Default time range, as a duration string.

    refreshInterval string

    Auto-refresh interval, as a duration string.

    variables object[]
    panels object

    Panel definitions, keyed by panel name.

    layouts object[]

    Grid layouts placing the panels.

    datasources object

    Datasources scoped to this dashboard, keyed by name.

    version integer

    Revision number. Starts at 1 and increments on every update.

    createdBy integer

    Numeric id of the principal that created the dashboard. For a dashboard created through this API this is the id of the API token, not of a user.

    updatedBy integer

    Numeric id of the principal that last updated the dashboard.

    createdAt date-time

    When this version was written. An update stamps a new value, so this is not the creation time of the original dashboard.

    updatedAt date-time
    isPrivate boolean

    Whether the dashboard was made private in the Logz.io app. Privacy can't be changed through this API, and dashboards created through it are never private.

    isDeleted boolean
    deletedAt date-time

    Null unless the dashboard was deleted.

    deletedBy integer

    Null unless the dashboard was deleted.

  • ]
  • ]
Loading...