Project Management

Read Project

Introduction

List details of all projects, or the project matched the passed project ID if the project ID property passed.

Request

The projectId for the project to read, or nothing to get a details list of all projects. The /projects/read API accepts requests in the following format:

ReadProjectRequest Model - Request to get details about a specific project or a subset of your projects.
projectId integer
example: 23456789
Id of the project to read.
start integer
example: 0
Starting (inclusive, zero-based) index of the projects to fetch. If you provide this property, omit the project Id property.
end integer
example: 100
Last (exlusive) index of the projects to fetch. If you provide this property, omit the project Id property.
Example 
{
  "projectId": 23456789,
  "start": 0,
  "end": 100
}

Responses

The /projects/read API provides a response in the following format:

200 Success

ProjectListResponse Model - Project list response.
projects Project Array
List of projects for the authenticated user.
versions LeanVersion Array
List of LEAN versions.
success boolean
Indicate if the API request was successful.
errors string Array
List of errors with the API call.
Example 
{
  "projects": [
    {
      "projectId": 23456789,
      "organizationId": "5cad178b20a1d52567b534553413b691",
      "name": "string",
      "modified": "2021-11-26T15:18:27.693Z",
      "created": "2021-11-26T15:18:27.693Z",
      "ownerId": 0,
      "language": "C#",
      "collaborators": [
        {
          "uid": 0,
          "liveControl": true,
          "permission": "read",
          "publicId": "string",
          "profileImage": "https://cdn.quantconnect.com/web/i/users/profile/abc123.jpeg",
          "email": "abc@123.com",
          "name": "string",
          "bio": "string",
          "owner": true
        }
      ],
      "leanVersionId": 0,
      "leanPinnedToMaster": true,
      "owner": true,
      "description": "string",
      "channelId": "string",
      "parameters": ,
      "libraries": [
        {
          "projectId": 23456789,
          "libraryName": "string",
          "ownerName": "string",
          "access": true
        }
      ],
      "grid": {
        "xs": [
          {
            "chartName": "string",
            "width": 0,
            "height": 0,
            "row": 0,
            "column": 0,
            "sort": 0,
            "definition": [
              "string"
            ]
          }
        ],
        "sm": [
          {
            "chartName": "string",
            "width": 0,
            "height": 0,
            "row": 0,
            "column": 0,
            "sort": 0,
            "definition": [
              "string"
            ]
          }
        ],
        "md": [
          {
            "chartName": "string",
            "width": 0,
            "height": 0,
            "row": 0,
            "column": 0,
            "sort": 0,
            "definition": [
              "string"
            ]
          }
        ],
        "lg": [
          {
            "chartName": "string",
            "width": 0,
            "height": 0,
            "row": 0,
            "column": 0,
            "sort": 0,
            "definition": [
              "string"
            ]
          }
        ],
        "xl": [
          {
            "chartName": "string",
            "width": 0,
            "height": 0,
            "row": 0,
            "column": 0,
            "sort": 0,
            "definition": [
              "string"
            ]
          }
        ]
      },
      "liveGrid": {
        "xs": [
          {
            "chartName": "string",
            "width": 0,
            "height": 0,
            "row": 0,
            "column": 0,
            "sort": 0,
            "definition": [
              "string"
            ]
          }
        ],
        "sm": [
          {
            "chartName": "string",
            "width": 0,
            "height": 0,
            "row": 0,
            "column": 0,
            "sort": 0,
            "definition": [
              "string"
            ]
          }
        ],
        "md": [
          {
            "chartName": "string",
            "width": 0,
            "height": 0,
            "row": 0,
            "column": 0,
            "sort": 0,
            "definition": [
              "string"
            ]
          }
        ],
        "lg": [
          {
            "chartName": "string",
            "width": 0,
            "height": 0,
            "row": 0,
            "column": 0,
            "sort": 0,
            "definition": [
              "string"
            ]
          }
        ],
        "xl": [
          {
            "chartName": "string",
            "width": 0,
            "height": 0,
            "row": 0,
            "column": 0,
            "sort": 0,
            "definition": [
              "string"
            ]
          }
        ]
      },
      "paperEquity": 0,
      "lastLiveDeployment": "2021-11-26T15:18:27.693Z",
      "liveForm": {
        "brokerageData": {
          "id": "string",
          "authentication": 
        },
        "dataProvidersData": [
          {
            "id": "string"
          }
        ],
        "node": "string",
        "notifyInsights": true,
        "notifyOrderEvents": true,
        "autoRestart": true
      },
      "encrypted": true,
      "codeRunning": true,
      "leanEnvironment": 0,
      "encryptionKey": {
        "id": "string",
        "name": "string"
      },
      "isPinned": true,
      "maxFileSize": "string",
      "sharingTokenBacktest": "q"
    }
  ],
  "versions": [
    {
      "id": 0,
      "created": "2021-11-26T15:18:27.693Z",
      "description": "string",
      "leanHash": "string",
      "leanCloudHash": "string",
      "name": "string",
      "ref": "string",
      "public": true
    }
  ],
  "success": true,
  "errors": [
    "string"
  ]
}
Project Model - Response from reading a project by id.
projectId integer
required
example: 23456789
Project id.
organizationId string
required
example: 5cad178b20a1d52567b534553413b691
Organization id.
name string
required
Name of the project.
modified string($date-time)
required
Modified date for the project.
created string($date-time)
required
Date the project was created.
ownerId integer
required
Owner id.
language string Enum
required
Programming language of the project. Options : ['C#', 'Py']
collaborators Collaborator Array
required
List of collaborators.
leanVersionId integer
required
The version of LEAN this project is running on.
leanPinnedToMaster boolean
required
Indicate if the project is pinned to the master branch of LEAN.
owner boolean
required
Indicate if you are the owner of the project.
description string
required
The project description.
channelId string
required
Channel id.
parameters ParameterSet object
required
Optimization parameters.
libraries Library Array
required
The library projects.
grid object
required
Configuration of the backtest view grid.
liveGrid object
required
Configuration of the live view grid.
paperEquity number
required
The equity value of the last paper trading instance.
lastLiveDeployment string($date-time)
required
The last live deployment active time.
liveForm object
required
The last live wizard content used.
encrypted boolean
required
Indicates if the project is encrypted.
codeRunning boolean
required
Indicates if the project is running or not.
leanEnvironment integer
required
LEAN environment of the project running on.
encryptionKey object
required
Text file with at least 32 characters to be used to encrypt the project.
isPinned boolean
required
Indicates if the projects is pinned in the terminal landing page.
maxFileSize int
required
Indicates if the maximum file length.
sharingTokenBacktest string
example: q
Text file with at least 64 characters to be used to authenticate private backtests requests.
Example 
{
  "projectId": 23456789,
  "organizationId": "5cad178b20a1d52567b534553413b691",
  "name": "string",
  "modified": "2021-11-26T15:18:27.693Z",
  "created": "2021-11-26T15:18:27.693Z",
  "ownerId": 0,
  "language": "C#",
  "collaborators": [
    {
      "uid": 0,
      "liveControl": true,
      "permission": "read",
      "publicId": "string",
      "profileImage": "https://cdn.quantconnect.com/web/i/users/profile/abc123.jpeg",
      "email": "abc@123.com",
      "name": "string",
      "bio": "string",
      "owner": true
    }
  ],
  "leanVersionId": 0,
  "leanPinnedToMaster": true,
  "owner": true,
  "description": "string",
  "channelId": "string",
  "parameters": ,
  "libraries": [
    {
      "projectId": 23456789,
      "libraryName": "string",
      "ownerName": "string",
      "access": true
    }
  ],
  "grid": {
    "xs": [
      {
        "chartName": "string",
        "width": 0,
        "height": 0,
        "row": 0,
        "column": 0,
        "sort": 0,
        "definition": [
          "string"
        ]
      }
    ],
    "sm": [
      {
        "chartName": "string",
        "width": 0,
        "height": 0,
        "row": 0,
        "column": 0,
        "sort": 0,
        "definition": [
          "string"
        ]
      }
    ],
    "md": [
      {
        "chartName": "string",
        "width": 0,
        "height": 0,
        "row": 0,
        "column": 0,
        "sort": 0,
        "definition": [
          "string"
        ]
      }
    ],
    "lg": [
      {
        "chartName": "string",
        "width": 0,
        "height": 0,
        "row": 0,
        "column": 0,
        "sort": 0,
        "definition": [
          "string"
        ]
      }
    ],
    "xl": [
      {
        "chartName": "string",
        "width": 0,
        "height": 0,
        "row": 0,
        "column": 0,
        "sort": 0,
        "definition": [
          "string"
        ]
      }
    ]
  },
  "liveGrid": {
    "xs": [
      {
        "chartName": "string",
        "width": 0,
        "height": 0,
        "row": 0,
        "column": 0,
        "sort": 0,
        "definition": [
          "string"
        ]
      }
    ],
    "sm": [
      {
        "chartName": "string",
        "width": 0,
        "height": 0,
        "row": 0,
        "column": 0,
        "sort": 0,
        "definition": [
          "string"
        ]
      }
    ],
    "md": [
      {
        "chartName": "string",
        "width": 0,
        "height": 0,
        "row": 0,
        "column": 0,
        "sort": 0,
        "definition": [
          "string"
        ]
      }
    ],
    "lg": [
      {
        "chartName": "string",
        "width": 0,
        "height": 0,
        "row": 0,
        "column": 0,
        "sort": 0,
        "definition": [
          "string"
        ]
      }
    ],
    "xl": [
      {
        "chartName": "string",
        "width": 0,
        "height": 0,
        "row": 0,
        "column": 0,
        "sort": 0,
        "definition": [
          "string"
        ]
      }
    ]
  },
  "paperEquity": 0,
  "lastLiveDeployment": "2021-11-26T15:18:27.693Z",
  "liveForm": {
    "brokerageData": {
      "id": "string",
      "authentication": 
    },
    "dataProvidersData": [
      {
        "id": "string"
      }
    ],
    "node": "string",
    "notifyInsights": true,
    "notifyOrderEvents": true,
    "autoRestart": true
  },
  "encrypted": true,
  "codeRunning": true,
  "leanEnvironment": 0,
  "encryptionKey": {
    "id": "string",
    "name": "string"
  },
  "isPinned": true,
  "maxFileSize": "string",
  "sharingTokenBacktest": "q"
}
Collaborator Model
uid integer
required
User ID.
liveControl boolean
required
Indicate if the user has live control.
permission string Enum
required
The permission this user is given. Options : ['read', 'write']
publicId string
required
The user public ID.
profileImage string
required
example: https://cdn.quantconnect.com/web/i/users/profile/abc123.jpeg
The url of the user profile image.
email string
required
example: abc@123.com
The registered email of the user.
name string
required
The display name of the user.
bio string
required
The biography of the user.
owner boolean
required
Indicate if the user is the owner of the project.
Example 
{
  "uid": 0,
  "liveControl": true,
  "permission": "read",
  "publicId": "string",
  "profileImage": "https://cdn.quantconnect.com/web/i/users/profile/abc123.jpeg",
  "email": "abc@123.com",
  "name": "string",
  "bio": "string",
  "owner": true
}
Library Model
projectId integer
required
example: 23456789
Project Id of the library project.
libraryName string
Name of the library project.
ownerName string
Name of the library project owner.
access boolean
Indicate if the library project can be accessed.
Example 
{
  "projectId": 23456789,
  "libraryName": "string",
  "ownerName": "string",
  "access": true
}
Grid Model - The grid arrangement of charts.
xs GridChart Array
required
List of chart in the xs (Extra small) position.
sm GridChart Array
required
List of chart in the sm (Small) position.
md GridChart Array
required
List of chart in the md (Medium) position.
lg GridChart Array
required
List of chart in the lg (Large) position.
xl GridChart Array
required
List of chart in the xl (Extra large) position.
Example 
{
  "xs": [
    {
      "chartName": "string",
      "width": 0,
      "height": 0,
      "row": 0,
      "column": 0,
      "sort": 0,
      "definition": [
        "string"
      ]
    }
  ],
  "sm": [
    {
      "chartName": "string",
      "width": 0,
      "height": 0,
      "row": 0,
      "column": 0,
      "sort": 0,
      "definition": [
        "string"
      ]
    }
  ],
  "md": [
    {
      "chartName": "string",
      "width": 0,
      "height": 0,
      "row": 0,
      "column": 0,
      "sort": 0,
      "definition": [
        "string"
      ]
    }
  ],
  "lg": [
    {
      "chartName": "string",
      "width": 0,
      "height": 0,
      "row": 0,
      "column": 0,
      "sort": 0,
      "definition": [
        "string"
      ]
    }
  ],
  "xl": [
    {
      "chartName": "string",
      "width": 0,
      "height": 0,
      "row": 0,
      "column": 0,
      "sort": 0,
      "definition": [
        "string"
      ]
    }
  ]
}
GridChart Model - The chart display properties.
chartName string
required
The chart name.
width integer
required
Width of the chart.
height integer
required
Height of the chart.
row integer
required
Number of rows of the chart.
column integer
required
Number of columns of the chart.
sort integer
Sort of the chart.
definition string Array
The chart definition labels.
Example 
{
  "chartName": "string",
  "width": 0,
  "height": 0,
  "row": 0,
  "column": 0,
  "sort": 0,
  "definition": [
    "string"
  ]
}
LiveForm Model - The live wizard content used.
brokerageData object
required
/.
dataProvidersData BrokerageId Array
required
The data providers used in the live deployment.
node string
required
Node ID of the live node deployed.
notifyInsights boolean
required
Indicates if notification should be issued on new insights.
notifyOrderEvents boolean
required
Indicates if notification should be issued on new order events.
autoRestart boolean
required
Indicates if the live algorithm should automatically restart after encountering runtime errors.
Example 
{
  "brokerageData": {
    "id": "string",
    "authentication": 
  },
  "dataProvidersData": [
    {
      "id": "string"
    }
  ],
  "node": "string",
  "notifyInsights": true,
  "notifyOrderEvents": true,
  "autoRestart": true
}
BrokerageData Model - Brokerage data saved on live deployment.
id string
required
The ID of the brokerage data.
authentication object
Authentication details of the live brokerage. Details on each brokerage refers to https://www.quantconnect.com/docs/v2/lean-cli/api-reference/lean-cloud-live-deploy.
Example 
{
  "id": "string",
  "authentication": 
}
LiveAuthenticationData Model - Authentication details of the live brokerage. Details on each brokerage refers to https://www.quantconnect.com/docs/v2/lean-cli/api-reference/lean-cloud-live-deploy.
value object
Authentication details of the live brokerage. Details on each brokerage refers to https://www.quantconnect.com/docs/v2/lean-cli/api-reference/lean-cloud-live-deploy.
Example 
{
  "value": 
}
BrokerageId Model - Brokerage Id.
id string
The ID of the brokerage.
Example 
{
  "id": "string"
}
EncryptionKey Model - Encryption key details.
id string
Encryption key id.
name string
Name of the encryption key.
Example 
{
  "id": "string",
  "name": "string"
}
LeanVersion Model
id integer
Id of the LEAN version.
created string($date-time)
Date when this version was created.
description string
Description of the LEAN version.
leanHash string
Commit Hash in the LEAN repository.
leanCloudHash string
Commit Hash in the LEAN Cloud repository.
name string
Name of the branch where the commit is.
ref string
Reference to the branch where the commit is.
public boolean
Indicates if the version is available for the public.
Example 
{
  "id": 0,
  "created": "2021-11-26T15:18:27.693Z",
  "description": "string",
  "leanHash": "string",
  "leanCloudHash": "string",
  "name": "string",
  "ref": "string",
  "public": true
}

401 Authentication Error

UnauthorizedError Model - Unauthorized response from the API. Key is missing, invalid, or timestamp is too old for hash.
www_authenticate string
Header

Examples

The following examples demonstrate project management through the QuantConnect API.

Example 1: CRUD Operations

This example demonstates creating, reading, updating, and deleting a project through the cloud API.

from base64 import b64encode
from hashlib import sha256
from time import time
from requests import get, post
BASE_URL = 'https://www.quantconnect.com/api/v2/'

# You need to replace these with your actual credentials.
# You can request your credentials at https://www.quantconnect.com/settings/
# You can find our organization ID at https://www.quantconnect.com/organization/ 
USER_ID = 0
API_TOKEN = '____'
ORGANIZATION_ID = '____'

def get_headers():
    # Get timestamp
    timestamp = f'{int(time())}'
    time_stamped_token = f'{API_TOKEN}:{timestamp}'.encode('utf-8')

    # Get hased API token
    hashed_token = sha256(time_stamped_token).hexdigest()
    authentication = f'{USER_ID}:{hashed_token}'.encode('utf-8')
    authentication = b64encode(authentication).decode('ascii')

    # Create headers dictionary.
    return {
        'Authorization': f'Basic {authentication}',
        'Timestamp': timestamp
    }

# Authenticate to verify credentials
response = post(f'{BASE_URL}/authenticate', headers = get_headers())
print(response.json())

# --------------------


# The project ID of the project to manage
project_id = 12345678

### Create Project
# Send a POST request to the /projects/create endpoint to create a new project
response = post(f'{BASE_URL}/projects/create', headers=get_headers(), json={
    "name": f"Project_{int(time())}",  # Unique project name using current timestamp
    "language": "Py"  # Programming language for the project (Python)
})
# Parse the JSON response into python managable dict
result = response.json()
# Extract the project ID from the response
project_id = result['projects'][0]['projectId']
# Check if the request was successful and print the result
if result['success']:
    print("Project Created Successfully:")
    print(result)

### Read Project
# Prepare data payload to read project details
payload = {
    "id": project_id  # ID of the project to read
}
# Send a POST request to the /projects/read endpoint to get project details
response = post(f'{BASE_URL}/projects/read', headers=get_headers(), json=payload)
# Parse the JSON response into python managable dict
result = response.json()
# Check if the request was successful and print the project details
if result['success']:
    print("Project Details:")
    print(result)

### Update Project
# Send a POST request to the /projects/update endpoint to update project details
response = post(f'{BASE_URL}/projects/update', headers=get_headers(), json={
    "projectId": project_id,  # ID of the project to update
    "name": f"Project_{project_id}",  # New name for the project
    "description": "The new project name is awesome!"  # New description
})
# Parse the JSON response into python managable dict
result = response.json()
# Check if the request was successful and print the result
if result['success']:
    print("Project Updated Successfully:")
    print(result)

### Delete Project
# Prepare data payload to delete the project
payload = {
    "projectId": project_id  # ID of the project to delete
}
# Send a POST request to the /projects/delete endpoint to delete the project
response = post(f'{BASE_URL}/projects/delete', headers=get_headers(), json=payload)
# Parse the JSON response into python managable dict
result = response.json()
# Check if the request was successful and print the result
if result['success']:
    print("Project Deleted Successfully:")
    print(result)

Example 2: Delete All Projects in a Directory

This example deletes all projects under a specific directory in the organization workspace.

from base64 import b64encode
from hashlib import sha256
from time import time
from requests import get, post
BASE_URL = 'https://www.quantconnect.com/api/v2/'

# You need to replace these with your actual credentials.
# You can request your credentials at https://www.quantconnect.com/settings/
# You can find our organization ID at https://www.quantconnect.com/organization/ 
USER_ID = 0
API_TOKEN = '____'
ORGANIZATION_ID = '____'

def get_headers():
    # Get timestamp
    timestamp = f'{int(time())}'
    time_stamped_token = f'{API_TOKEN}:{timestamp}'.encode('utf-8')

    # Get hased API token
    hashed_token = sha256(time_stamped_token).hexdigest()
    authentication = f'{USER_ID}:{hashed_token}'.encode('utf-8')
    authentication = b64encode(authentication).decode('ascii')

    # Create headers dictionary.
    return {
        'Authorization': f'Basic {authentication}',
        'Timestamp': timestamp
    }

# Authenticate to verify credentials
response = post(f'{BASE_URL}/authenticate', headers = get_headers())
print(response.json())

# --------------------

def get_projects_in_directory(key):
    """Get all projects in a specific directory in the organization 
    workspace.

    Keyword arguments:
    key -- path to a directory of projects in the organization workspace
           (ex: path/to/dir)
    """
    # Split the key into path segments.
    key_segments = [s for s in key.split('/') if s]
    if not key_segments:
        print('Invalid key:', key)
        return
    # Iterate through all projects
    response = post(f'{BASE_URL}/projects/read', headers=get_headers())
    response.raise_for_status()
    project_ids = []
    for project in response.json()['projects']:
        # Check if the project is in the directory.
        if all(a == b for a, b in zip(key_segments, project['name'].split('/'))):
            project_ids.append(project['projectId'])
    return project_ids

def delete_projects(project_ids):
    """Delete a set of projects.

    Keyword arguments:
    project_ids -- list of project Ids.
    """
    for id_ in project_ids:
        post(
            f'{BASE_URL}/projects/delete', 
            headers=get_headers(), 
            json={'projectId': id_}
        ).raise_for_status()

delete_projects(get_projects_in_directory('/path/to/projects/to/delete'))

You can also see our Videos. You can also get in touch with us via Discord.

Did you find this page helpful?

Contribute to the documentation: