GET/projects/api/v3/summary.json

Get installation summary dashboard

Retrieves the summary from the entire installation, returning counters about tasks, milestones, columns, events, risks, timers, projects healths.

On this endpoint you can filter by project custom fields. The syntax for the query parameter is the following:

projectCustomField[id][op]=value

Where:

  • [id] is the custom field ID
  • [op] is the operator to apply when filtering, different operators are allowed according to the custom field type
  • [value] is the value to apply when filtering

For example, if I want to filter a dropdown custom field with ID 10 to only return entries that have the value "Option1" we would do the following:

projectCustomField[10][eq]=Option1

The allowed operators are:

  • like
  • not-like
  • eq
  • not
  • lt
  • gt
  • any

Query Params

  • Name
    until
    Type
    string
    Description

    used to limit the since counters to a specific period

    Allowed values
    • now
    • timeRange
  • Name
    timeRangeStart
    Type
    string
    Description

    filter by start datetime

  • Name
    timeRangeEnd
    Type
    string
    Description

    filter by end datetime

  • Name
    timeRange
    Type
    string
    Description

    filter by time range. It will be ignored if timeRangeStart and timeRangeEnd are provided.

    Allowed values
    • yesterday
    • today
    • thisweek
    • lastweek
    • thismonth
    • lastmonth
    • last3months
    • last6months
  • Name
    status
    Type
    string
    Description

    project status (deprecated, use projectStatuses)

    Allowed values
    • active
    • current
    • late
    • upcoming
    • completed
    • deleted
  • Name
    projectStatus
    Type
    string
    Description

    project status

    Allowed values
    • active
    • current
    • late
    • upcoming
    • completed
    • deleted
  • Name
    eventsDaysAhead
    Type
    integer
    Description

    number of days remaining to event's start

    Default
    7
  • Name
    useStartDatesForTodaysTasks
    Type
    boolean
    Description

    enforce today is considered as start date for today's tasks

  • Name
    unreadMessagesMineOnly
    Type
    boolean
    Description

    filter by my unread messages only

  • Name
    unreadCommentsMineOnly
    Type
    boolean
    Description

    filter by my unread comments only

  • Name
    onlyStarredProjects
    Type
    boolean
    Description

    filter by starred projects only

  • Name
    onlyProjectEvents
    Type
    boolean
    Description

    filter only project events

  • Name
    matchAllTags
    Type
    boolean
    Description

    enforce all tag ids must be matched (deprecated, use matchAllProjectTags)

  • Name
    matchAllProjectTags
    Type
    boolean
    Description

    enforce all tag ids must be matched

  • Name
    includeAssigneeTeams
    Type
    boolean
    Description

    include teams related to the taskAssigneeUserIds

  • Name
    includeArchivedProjects
    Type
    boolean
    Description

    include archived projects

  • Name
    eventsAttendingOnly
    Type
    boolean
    Description

    count only events that the users are attending

  • Name
    applyTaskAssigneeUsersToSince
    Type
    boolean
    Description

    the since section will only use taskAssigneeUserIds if this flag is true (keeps backward compatibility)

  • Name
    applySinceOnUnread
    Type
    boolean
    Description

    when enabled unread counters will respect the time range period.

    Default
    false
  • Name
    userIds
    Type
    array[integer]
    Description

    filter by user ids

    Format
    Comma separated values
  • Name
    timeLoggedByUserIds
    Type
    array[integer]
    Description

    filter by user ids who time logged

    Format
    Comma separated values
  • Name
    taskAssigneeUserIds
    Type
    array[integer]
    Description

    filter by user ids with tasks assigned

    Format
    Comma separated values
  • Name
    projectTagIds
    Type
    array[integer]
    Description

    filter by project tag ids

    Format
    Comma separated values
  • Name
    projectStatuses
    Type
    array[string]
    Description

    project statuses

    Format
    Comma separated values
    Allowed values
    • active
    • current
    • late
    • upcoming
    • completed
    • deleted
  • Name
    projectOwnerIds
    Type
    array[integer]
    Description

    filter by project owner ids

    Format
    Comma separated values
  • Name
    projectIds
    Type
    array[integer]
    Description

    filter by project ids

    Format
    Comma separated values
  • Name
    projectHealths
    Type
    array[integer]
    Description

    project healths

    0: not set 1: bad 2: ok 3: good

    Format
    Comma separated values
    Allowed values
    • 0
    • 1
    • 2
    • 3
  • Name
    projectHealth
    Type
    array[integer]
    Description

    project healths (deprecated, use projectHealths)

    0: not set 1: bad 2: ok 3: good

    Format
    Comma separated values
    Allowed values
    • 0
    • 1
    • 2
    • 3
  • Name
    projectCompanyIds
    Type
    array[integer]
    Description

    filter by company ids

    Format
    Comma separated values
  • Name
    projectCategoryIds
    Type
    array[integer]
    Description

    filter by project category ids

    Format
    Comma separated values
  • Name
    milestoneAssigneeUserIds
    Type
    array[integer]
    Description

    filter by user ids with milestones assigned

    Format
    Comma separated values
  • Name
    filterTagIds
    Type
    array[integer]
    Description

    filter by project tag ids (deprecated, use projectTagIds)

    Format
    Comma separated values
  • Name
    fields[unread]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • comments
    • messages
  • Name
    fields[time]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • estimates
    • totals
  • Name
    fields[tasks]
    Type
    array[string]
    Description

    sparse fields

    Format
    Comma separated values
    Allowed values
    • nodate
    • today
    • late
    • started
    • complete
    • upcoming
    • active
  • Name
    fields[stages]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • count
    • data
  • Name
    fields[since]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • tasksComplete
    • tasksCreated
    • events
    • dateTime
  • Name
    fields[risks]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • total
    • open
    • pending
    • closed
  • Name
    fields[milestones]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • today
    • late
    • complete
    • upcoming
    • active
  • Name
    fields[health]
    Type
    array[string]
    Description

    0: not set 1: bad 2: ok 3: good

    Format
    Comma separated values
    Allowed values
    • 0
    • 1
    • 2
    • 3
  • Name
    fields[events]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • today
    • upcoming
  • Name
    fields[columns]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • count
    • data
  • Name
    companyIds
    Type
    array[integer]
    Description

    filter by company ids (deprecated, use projectCompanyIds)

    Format
    Comma separated values
  • Name
    assigneeUserIds
    Type
    array[integer]
    Description

    filter by user ids with tasks or milestones assigned

    Format
    Comma separated values

Responses

  • Code
    200
    Type
    object
    Schema
    Description
    200 OK
    Response contains all the information returned when sending a GET request to the summary endpoint (dashboard).
  • Code
    400
    Type
    object
    Schema
    Description
    400 Bad Request
    ErrorResponse defines how []Error should be marshaled to JSON.

Examples

200 OK

Response
{
  "columns": {
    "count": 0,
    "data": [
      {
        "cards": {
          "active": 0,
          "archived": 0,
          "completed": 0,
          "count": 0
        },
        "color": "string",
        "estimatedTime": {
          "active": 0,
          "archived": 0,
          "completed": 0,
          "total": 0
        },
        "id": 0,
        "name": "string"
      }
    ]
  },
  "events": {
    "today": 0,
    "upcoming": 0
  },
  "health": {
    "0": 0,
    "1": 0,
    "2": 0,
    "3": 0
  },
  "milestones": {
    "active": 0,
    "complete": 0,
    "late": 0,
    "today": 0,
    "upcoming": 0
  },
  "risks": {
    "closed": 0,
    "open": 0,
    "pending": 0,
    "total": 0
  },
  "since": {
    "dateTime": "string",
    "events": 0,
    "tasksComplete": 0,
    "tasksCreated": 0
  },
  "tasks": {
    "active": 0,
    "complete": 0,
    "late": 0,
    "nodate": 0,
    "started": 0,
    "today": 0,
    "upcoming": 0
  },
  "time": {
    "estimates": {
      "activeMinsEstimated": 0,
      "completedMinsEstimated": 0,
      "totalMinsEstimated": 0,
      "totalWithTimeLoggedEstimatedMins": 0
    },
    "totals": {
      "billableMinsSum": 0,
      "billedMinsSum": 0,
      "nonBillableMinsSum": 0,
      "nonBilledMinsSum": 0,
      "totalMinsSum": 0
    }
  },
  "unread": {
    "comments": 0,
    "messages": 0
  }
}
Download Swagger