GET/projects/api/v3/projects/{projectId}/summary.json

Get project summary dashboard

Retrieves the summary from a specific project, 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

Path Params

  • Name
    projectId
    Type
    integer
    required
    Description

Query Params

  • Name
    until
    Type
    string
    Description
    used to limit the since counters to a specific period
  • 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
    were informed.
  • Name
    status
    Type
    string
    Description
    project status (deprecated, use projectStatuses)
  • Name
    projectStatus
    Type
    string
    Description
    project status
  • 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 health (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
    health
    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
    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
    • mine
    • all
  • Name
    fields[tasks]
    Type
    array[string]
    Description
    sparse fields
    Format
    Comma separated values
    Allowed values
    • everyone
    • mine
  • 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
    • everyone
    • mine
  • 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
    ProjectResponse contains all the information returned when sending a GET request to the summary endpoint (project).
  • Code
    400
    Type
    object
    Schema
    Description
    400 Bad Request
    ErrorResponse defines how []Error should be marshaled to JSON.

Examples

200 OK

ProjectResponse
{
  "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": {
    "everyone": {
      "active": 0,
      "complete": 0,
      "late": 0,
      "today": 0,
      "upcoming": 0
    },
    "mine": {
      "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": {
    "everyone": {
      "active": 0,
      "complete": 0,
      "late": 0,
      "nodate": 0,
      "started": 0,
      "today": 0,
      "upcoming": 0
    },
    "mine": {
      "active": 0,
      "complete": 0,
      "late": 0,
      "nodate": 0,
      "started": 0,
      "today": 0,
      "upcoming": 0
    },
    "user": {
      "active": 0,
      "complete": 0,
      "late": 0,
      "nodate": 0,
      "started": 0,
      "today": 0,
      "upcoming": 0
    }
  },
  "time": {
    "all": {
      "estimates": {
        "activeMinsEstimated": 0,
        "completedMinsEstimated": 0,
        "totalMinsEstimated": 0,
        "totalWithTimeLoggedEstimatedMins": 0
      },
      "totals": {
        "billableMinsSum": 0,
        "billedMinsSum": 0,
        "nonBillableMinsSum": 0,
        "nonBilledMinsSum": 0,
        "totalMinsSum": 0
      }
    },
    "mine": {
      "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
  }
}