Projects

Get a project

Changed on Aug 13, 2026

<b>Required scope: </b><code>projects:read</code>

<table> <tr> <th>Field</th> <th>Required Scope</th> </tr> <tr> <td><code>team</code></td> <td><code>teams:read</code></td> </tr> <tr> <td><code>custom_type</code></td> <td><code>custom_types:read</code></td> </tr> </table>

Returns the complete project record for a single project.

get/projects/{project_gid}

Request

Base URL: https://app.asana.com/api/1.0
URL: https://app.asana.com/api/1.0/projects/{project_gid}
Auth: one of:
- HTTP bearer
- OAuth 2 (authorization code, authorization URL https://app.asana.com/-/oauth_authorize, token URL https://app.asana.com/-/oauth_token, scopes: projects:read)

Query parameters

opt_fieldsstring[]

This endpoint returns a resource which excludes some properties by default. To include those optional properties, set this query parameter to a comma-separated list of the properties you wish to include. Properties can include nested fields. To learn more, see the input/output options guide.

Response

Successfully retrieved the requested project.

Example response

{
  "data": {
    "gid": "12345",
    "resource_type": "project",
    "name": "Stuff to buy",
    "resource_subtype": "default_project",
    "color": "light-green",
    "icon": "chat_bubbles",
    "created_at": "2012-02-22T02:06:58.147Z",
    "current_status": {
      "gid": "12345",
      "resource_type": "project_status",
      "title": "Status Update - Jun 15",
      "text": "The project is moving forward according to plan...",
      "html_text": "<body>The project <strong>is</strong> moving forward according to plan...</body>",
      "author": {
        "gid": "12345",
        "resource_type": "user",
        "name": "Greg Sanchez"
      },
      "created_at": "2012-02-22T02:06:58.147Z",
      "created_by": {
        "gid": "12345",
        "resource_type": "user",
        "name": "Greg Sanchez"
      },
      "modified_at": "2012-02-22T02:06:58.147Z"
    },
    "current_status_update": {
      "gid": "12345",
      "resource_type": "status_update",
      "title": "Status Update - Jun 15",
      "resource_subtype": "project_status_update"
    },
    "custom_field_settings": [
      {
        "gid": "12345",
        "resource_type": "custom_field_setting",
        "project": {
          "gid": "12345",
          "resource_type": "project",
          "name": "Stuff to buy",
          "resource_subtype": "default_project"
        },
        "parent": {
          "gid": "12345",
          "resource_type": "project",
          "name": "Stuff to buy",
          "resource_subtype": "default_project"
        },
        "custom_field": {
          "gid": "12345",
          "resource_type": "custom_field",
          "name": "Status",
          "enum_options": [
            {
              "gid": "12345",
              "resource_type": "enum_option",
              "name": "Low",
              "enabled": true,
              "color": "blue"
            }
          ],
          "enabled": true,
          "representation_type": "number",
          "id_prefix": "ID",
          "input_restrictions": [
            "task"
          ],
          "date_value": {
            "date": "2024-08-23",
            "date_time": "2024-08-23T22:00:00.000Z"
          },
          "enum_value": {
            "gid": "12345",
            "resource_type": "enum_option",
            "name": "Low",
            "enabled": true,
            "color": "blue"
          },
          "multi_enum_values": [
            {
              "gid": "12345",
              "resource_type": "enum_option",
              "name": "Low",
              "enabled": true,
              "color": "blue"
            }
          ],
          "number_value": 5.2,
          "text_value": "Some Value",
          "display_value": "blue",
          "description": "Development team priority",
          "precision": 2,
          "format": "custom",
          "currency_code": "EUR",
          "custom_label": "gold pieces",
          "custom_label_position": "suffix",
          "is_global_to_workspace": true,
          "has_notifications_enabled": true,
          "asana_created_field": "priority",
          "created_by": {
            "gid": "12345",
            "resource_type": "user",
            "name": "Greg Sanchez"
          },
          "people_value": [
            {
              "gid": "12345",
              "resource_type": "user",
              "name": "Greg Sanchez"
            }
          ],
          "reference_value": [
            {
              "gid": "12345",
              "resource_type": "task",
              "name": "Bug Task"
            }
          ],
          "html_text_value": "<body>Some Value</body>",
          "privacy_setting": "public_with_guests",
          "default_access_level": "user",
          "resource_subtype": "text"
        }
      }
    ],
    "default_view": "calendar",
    "due_date": "2019-09-15",
    "due_on": "2019-09-15",
    "html_notes": "<body>These are things we need to purchase.</body>",
    "members": [
      {
        "gid": "12345",
        "resource_type": "user",
        "name": "Greg Sanchez"
      }
    ],
    "modified_at": "2012-02-22T02:06:58.147Z",
    "notes": "These are things we need to purchase.",
    "privacy_setting": "public_to_workspace",
    "start_on": "2019-09-14",
    "default_access_level": "admin",
    "minimum_access_level_for_customization": "admin",
    "minimum_access_level_for_sharing": "admin",
    "custom_fields": [
      {
        "gid": "12345",
        "resource_type": "custom_field",
        "name": "Status",
        "enum_options": [
          {
            "gid": "12345",
            "resource_type": "enum_option",
            "name": "Low",
            "enabled": true,
            "color": "blue"
          }
        ],
        "enabled": true,
        "representation_type": "number",
        "id_prefix": "ID",
        "input_restrictions": [
          "task"
        ],
        "date_value": {
          "date": "2024-08-23",
          "date_time": "2024-08-23T22:00:00.000Z"
        },
        "enum_value": {
          "gid": "12345",
          "resource_type": "enum_option",
          "name": "Low",
          "enabled": true,
          "color": "blue"
        },
        "multi_enum_values": [
          {
            "gid": "12345",
            "resource_type": "enum_option",
            "name": "Low",
            "enabled": true,
            "color": "blue"
          }
        ],
        "number_value": 5.2,
        "text_value": "Some Value",
        "display_value": "blue"
      }
    ],
    "completed_at": "2012-02-22T02:06:58.147Z",
    "completed_by": {
      "gid": "12345",
      "resource_type": "user",
      "name": "Greg Sanchez"
    },
    "followers": [
      {
        "gid": "12345",
        "resource_type": "user",
        "name": "Greg Sanchez"
      }
    ],
    "owner": {
      "gid": "12345",
      "resource_type": "user",
      "name": "Greg Sanchez"
    },
    "team": {
      "gid": "12345",
      "resource_type": "team",
      "name": "Marketing"
    },
    "permalink_url": "https://app.asana.com/1/12345/project/123456789",
    "project_brief": {
      "gid": "12345",
      "resource_type": "project_brief"
    },
    "created_from_template": {
      "gid": "12345",
      "resource_type": "project_template",
      "name": "Packing list"
    },
    "workspace": {
      "gid": "12345",
      "resource_type": "workspace",
      "name": "My Company Workspace"
    },
    "custom_type": {
      "gid": "12345",
      "resource_type": "custom_type",
      "name": "Bug ticket",
      "asana_created_type_identifier": "COMMAND_TICKET"
    }
  }
}

Changes

Aug 13, 20262aac685725ec Revision changes
- info
  added the enum value custom_field_settings.parent.resource_subtype to the property items/ of the query request parameter opt_fields
- info
  added the enum value custom_field_settings.project.resource_subtype to the property items/ of the query request parameter opt_fields
- info
  added the enum value custom_type to the property items/ of the query request parameter opt_fields
- info
  added the enum value custom_type.asana_created_type_identifier to the property items/ of the query request parameter opt_fields
- info
  added the enum value custom_type.name to the property items/ of the query request parameter opt_fields
- info
  added the enum value resource_subtype to the property items/ of the query request parameter opt_fields
- info
  added the optional property ///////// to the response with the status
- info
  added the optional property ////////////// to the response with the status
- info
  added the optional property ////////////// to the response with the status
- info
  added the optional property // to the response with the status
May 21, 2026b3dcd9ce0bf2 Revision changes
- warning
  added the new goal enum value to the /////////////////////// response property for the response status
- warning
  added the new goal enum value to the //////////////// response property for the response status
- warning
  added the new goal enum value to the ///// response property for the response status
- warning
  added the new portfolio enum value to the /////////////////////// response property for the response status
- warning
  added the new portfolio enum value to the //////////////// response property for the response status
- warning
  added the new portfolio enum value to the ///// response property for the response status
- warning
  added the new project enum value to the /////////////////////// response property for the response status
- warning
  added the new project enum value to the //////////////// response property for the response status
- warning
  added the new project enum value to the ///// response property for the response status
- warning
  added the new reference enum value to the ////////////////////// response property for the response status
- warning
  added the new reference enum value to the ////////////////////// response property for the response status
- warning
  added the new reference enum value to the //// response property for the response status
- warning
  added the new reference enum value to the //// response property for the response status
- warning
  added the new task enum value to the /////////////////////// response property for the response status
- warning
  added the new task enum value to the //////////////// response property for the response status
- warning
  added the new task enum value to the ///// response property for the response status

Operation history (3 revisions)