GET/projects/api/v3/projects.json

Returns a list of projects

Retrieve all projects for the provided filters. Only the projects that the logged-in user can access will be returned.

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
    updatedAfter
    Type
    string
    Description

    updated after

  • Name
    timeMode
    Type
    string
    Description

    profitability time mode

    Allowed values
    • timelogs
    • estimated
  • Name
    searchTerm
    Type
    string
    Description

    filter by project name

  • Name
    reportType
    Type
    string
    Description

    define the type of the report

    Default
    project
    Allowed values
    • project
    • health
  • Name
    reportTimezone
    Type
    string
    Description

    Optional to configure the report dates displayed in a timezone

  • Name
    reportFormat
    Type
    string
    Description

    define the format of the report

    Default
    pdf
    Allowed values
    • csv
    • html
    • pdf
    • xls
  • Name
    projectType
    Type
    string
    Description

    filter by project type

  • Name
    orderMode
    Type
    string
    Description

    order mode

    Default
    asc
    Allowed values
    • asc
    • desc
  • Name
    orderBy
    Type
    string
    Description

    order by

    Default
    name
    Allowed values
    • companyname
    • datecreated
    • duedate
    • lastactivity
    • name
    • namecaseinsensitive
    • ownercompany
    • starred
    • categoryname
  • Name
    notCompletedBefore
    Type
    string
    Description

    filter by projects that have not been completed before the given date

  • Name
    minLastActivityDate
    Type
    string
    Description

    filter by min last activity date

  • Name
    maxLastActivityDate
    Type
    string
    Description

    filter by max last activity date

  • Name
    userId
    Type
    integer
    Description

    filter by user id

  • Name
    pageSize
    Type
    integer
    Description

    number of items in a page (not used when generating reports)

    Default
    50
  • Name
    page
    Type
    integer
    Description

    page number (not used when generating reports)

    Default
    1
  • Name
    orderByCustomFieldId
    Type
    integer
    Description

    order by custom field id when orderBy is equal to customfield

  • Name
    minBudgetCapacityUsedPercent
    Type
    integer
    Description

    filter by minimum budget capacity used

  • Name
    maxBudgetCapacityUsedPercent
    Type
    integer
    Description

    filter by maximum budget capacity used

  • Name
    useFormulaFields
    Type
    boolean
    Description

    use formula fields

  • Name
    skipCounts
    Type
    boolean
    Description

    SkipCounts allows you to skip doing counts on a list API endpoint for performance reasons.

  • Name
    searchCompanies
    Type
    boolean
    Description

    include companies in the search

  • Name
    searchByLetter
    Type
    boolean
    Description

    search projects beginning with the search term character only when it contains a single character.

  • Name
    onlyStarredProjects
    Type
    boolean
    Description

    filter by starred projects only

  • Name
    onlyProjectsWithExplicitMembership
    Type
    boolean
    Description

    only show projects with explicit membership

    Default
    false
  • Name
    onlyProjectsThatCanLogTime
    Type
    boolean
    Description

    can log time on projects

    Default
    false
  • Name
    onlyArchivedProjects
    Type
    boolean
    Description

    return only archived projects

    Default
    false
  • Name
    matchAllProjectTags
    Type
    boolean
    Description

    match all project tags

  • Name
    matchAllExcludedTags
    Type
    boolean
    Description

    match all excluded project tags

  • Name
    isReportDownload
    Type
    boolean
    Description

    generate a report document

    Default
    false
  • Name
    includeTentativeProjects
    Type
    boolean
    Description

    include alongside normal projects, tentative ones

  • Name
    includeSubCategories
    Type
    boolean
    Description

    include sub categories when filtering by ids

  • Name
    includeStats
    Type
    boolean
    Description

    include project status counts for tasks columns billing events milestones

  • Name
    includeProjectUserInfo
    Type
    boolean
    Description

    fetch user-specific data such as isStarred

    Default
    false
  • Name
    includeProjectProfitability
    Type
    boolean
    Description

    include project profitability in response

  • Name
    includeProjectDates
    Type
    boolean
    Description

    include minimum and maximum start/end dates for projects

  • Name
    includeCustomFields
    Type
    boolean
    Description

    include custom fields

    Default
    false
  • Name
    includeCounts
    Type
    boolean
    Description

    include project related counts

  • Name
    includeCompletedStatus
    Type
    boolean
    Description

    optional to include completed projects when filtering by project statuses "current,late".

  • Name
    includeArchivedProjects
    Type
    boolean
    Description

    include archived projects

    Default
    false
  • Name
    hideObservedProjects
    Type
    boolean
    Description

    hide projects where the logged-in user is just an observer

    Default
    false
  • Name
    alwaysIncludeFiltering
    Type
    boolean
    Description

    includes filters when project ids are provided

  • Name
    usersWithExplicitMembershipIds
    Type
    array[integer]
    Description

    only show projects that have an explicit common membership with provided user ids

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

    filter by projects that contain users associated with the team ids

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

    select the columns to use in exports.

    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

    filter by project status

    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

    filter by project healths

    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
    includeCustomFieldIds
    Type
    array[integer]
    Description

    include specific custom fields

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

    include (not used when generating reports)

    Format
    Comma separated values
    Allowed values
    • projectOwners
    • projectUpdates
    • companies
    • companies.countries
    • companies.industries
    • projectCategories
    • portfolioCards
    • portfolioBoards
    • portfolioColumns
    • tags
    • customfields
    • customfieldProjects
    • projectBudgets
    • activities.latest
    • users
    • createdBy
    • updatedBy
    • completedBy
    • deletedBy
  • Name
    fields[workflows]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • name
    • statusId
  • Name
    fields[users]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • firstName
    • lastName
    • title
    • email
    • companyId
    • company
    • isAdmin
    • isClientUser
    • isServiceAccount
    • type
    • deleted
    • avatarUrl
    • lengthOfDay
    • workingHoursId
    • workingHour
    • userRate
    • userCost
    • canAddProjects
  • Name
    fields[tags]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • name
    • color
    • count
  • Name
    fields[stages]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • name
    • stage
  • Name
    fields[projects]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • name
  • Name
    fields[projectcategories]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • name
    • color
    • count
    • parent
    • parentId
  • Name
    fields[projectUpdates]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • projectId
    • text
    • isActive
    • health
    • color
    • dateCreated
    • deleted
    • deletedDate
    • numLikes
    • reactions
  • Name
    fields[projectBudgets]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • projectId
    • type
    • status
    • capacityUsed
    • capacity
    • originatorBudgetId
    • isRepeating
    • repeatPeriod
    • repeatUnit
    • repeatsRemaining
    • sequenceNumber
    • startDateTime
    • endDateTime
    • currencyCode
    • timelogType
    • expenseType
    • defaultRate
    • notificationIds
    • createdByUserId
    • dateCreated
    • updatedUserId
    • dateUpdated
    • completedByUserId
    • dateCompleted
    • deletedByUserId
    • dateDeleted
  • Name
    fields[portfolioColumns]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • name
    • color
  • Name
    fields[portfolioCards]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • columnId
    • projectId
  • Name
    fields[portfolioBoards]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • name
    • color
  • Name
    fields[industries]
    Type
    array[string]
    Description
    Format
    Comma separated values
  • Name
    fields[customfields]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • projectId
    • entity
    • name
    • description
    • type
    • options
    • visibilities
    • isPrivate
    • required
    • createdAt
    • createdByUserId
    • updatedAt
    • updatedByUserId
    • deleted
    • deletedAt
    • deletedByUserId
  • Name
    fields[customfieldProjects]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • customfieldId
    • value
    • createdAt
    • createdBy
  • Name
    fields[countries]
    Type
    array[string]
    Description
    Format
    Comma separated values
  • Name
    fields[companies]
    Type
    array[string]
    Description
    Format
    Comma separated values
    Allowed values
    • id
    • name
    • logoUploadedToServer
    • logoImage
  • Name
    featuresEnabled
    Type
    array[string]
    Description

    filter by projects that have features enabled

    Format
    Comma separated values
    Allowed values
    • list
    • board
    • gantt
    • table
    • dashboard
    • milestones
    • messages
    • files
    • time
    • notebooks
    • risks
    • links
    • billing
    • comments
    • people
    • settings
  • Name
    excludeTagIds
    Type
    array[integer]
    Description

    exclude by project tag ids

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

    exclude certain project ids

    Format
    Comma separated values

Responses

  • Code
    200
    Type
    object
    Schema
    Description
    200 OK
    projectsResponseV205 contains information about a group of projects.
  • Code
    400
    Type
    object
    Schema
    Description
    400 Bad Request
    ErrorResponse defines how []Error should be marshaled to JSON.
  • Code
    403
    Type
    object
    Schema
    Description
    403 Forbidden
    ErrorResponse defines how []Error should be marshaled to JSON.

Examples

200 OK

projectsResponseV205
{  "included": {    "activities": {      "additionalProp": {        "datetime": "string",        "description": "string",        "extraDescription": "string",        "id": 0,        "itemLink": "string",        "itemType": "string",        "latestType": "string",        "link": "string",        "user": {          "id": 0,          "meta": {},          "type": "string"        }      }
Download Swagger