Skip to main content

Search dashboard folders

POST 
/perses-public/api/v1/projects/search

Searches dashboards and returns them grouped by folder.

The search term applies to dashboards, not to folders: results lists every folder in the account whatever the term is, and only the nested dashboards arrays are filtered and paginated. total counts the matching dashboards, not the folders.

filter.searchTerm is matched as a case-insensitive substring of each dashboard's doc.metadata.name. filter.createdBy narrows the results to dashboards created by the given users; get those ids from Get dashboard creators.

For a flat list of dashboards without the folder grouping, use Search dashboards.

Request​

Body

    filter object
    searchTerm string

    Case-insensitive substring matched against each dashboard's doc.metadata.name. An empty or omitted term matches every dashboard.

    createdBy integer[]

    Numeric user ids from Get dashboard creators. Applied by Search dashboard folders; ignored by Search dashboards.

    pagination object
    pageNumber integer

    1-based page number. Defaults to 1.

    pageSize integer

    Number of dashboards per page. Defaults to 20.

Responses​

Every folder, carrying one page of matching dashboards.

Schema
    results object[]
  • 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.

  • ]
  • ]
    • total integer

    Number of matching dashboards before pagination. This counts dashboards, not folders.

    pagination object
    pageNumber integer

    1-based page number. Defaults to 1.

    pageSize integer

    Number of dashboards per page. Defaults to 20.

Loading...