Connecting to ClickUp#
First Steps with ClickUp#
Set up an account with ClickUp.
There are both free and paid options for this API.
Your account plan tier will limit the number of requests each API key can make per month. Current rate limits are available in ClickUp's documentation.
How to Connect DataDistillr to ClickUp#
To set up a data source connection for ClickUp, you will need to have:
- A unique name for your data source connection to be used in queries.
- An API key generated through your ClickUp account
Data Source Form#
To locate the ClickUp form, follow the steps in Connecting Your Data to DataDistillr. When you get to the window to choose the data source type, select API as shown below.
On the API screen, select ClickUp from the list of API types as shown in the image below.
The following form will appear. Instructions are below on how to find the information required to fill each field on the ClickUp API form.
Once you have filled out all the fields, press the green 'Save' button, and your API will be connected!
Enter any name that will help you recognize this data source from within your query window.
Acceptable Characters Include
- lowercase alphanumeric characters
An API key is generated within your account page. The following steps will navigate you to its location. Once created, copy the key and enter it in the ClickUp form under 'API key'.
In the ClickUp app, click your profile icon in the bottom left corner of the page.
In the API Token section, click Copy (or Regenerate to get a new API token and then Copy) to save the API token to your clipboard.
Please see ClickUp's API Reference for more on ClickUp's endpoints.
The table below shows a list of endpoints available to connect to within the DataDistillr application. If you need to connect to any endpoints not listed in the table below, please use the Custom APIs Form.
|Returns all of the tasks associated with the given list.
Note: custom_fields parameter currently inoperable using this endpoint.
|Returns all of the tasks associated with the given list, including custom fields.|
||task_id||Returns data associated with tasks given a specific list_id.
Note: Endpoint is currently inoperable for tasks that have custom fields.
||task_id||Returns data associated with tasks that include custom fields given a specific list_id.|
||team_id||archived||Returns all of the spaces associated with the given team.|
||space_id||archived||Returns all of the folders within the given space.|
||folder_id||archived||Returns all of the lists within the given folder.|
||space_id||archived||Returns all of the lists within the given space.|
||space_id||archived||Returns all of the tags associated with the given space.|
The endpoints above will display as follows in the nav tree once your API has successfully connected.
The following queries are intended to help you get started, and make life simpler querying within your API.
For the following examples, suppose that my ClickUp API data source was called
clickupapi2000, and I want to query an endpoint. The endpoint goes after the ClickUp data source name:
You must then enter the required parameter in the WHERE clause. Optional parameters can be added after the required parameters by adding 'AND' before each additional parameter.
WHERE Clause (required and optional parameters)
Get Tasks from Lists Endpoint#
This query returns 10 tasks within the specified list, including closed tasks. This query uses the optional parameter
This will work for both lists with and without custom fields, just replace the endpoint name accordingly.
Get Task Data from Tasks Endpoint#
This query returns task data for a specific task id.
This will work for both tasks with and without custom fields, just replace the endpoint name accordingly.
Get Spaces Endpoint#
This query returns 10 spaces associated with the specified team.
Get Folders from Space Endpoint#
This query returns 10 folders within the specified space.
Get Lists from Folder Endpoint#
This query returns 10 lists within the specified folder.
Get Lists from Space Endpoint#
This query returns 10 lists within the specified space.
Get Tags Endpoint#
This query returns 10 tags associated with the specified space.
Accessing Nested ClickUp API Data#
This query can be used to access nested ClickUp data found in custom fields within ClickUp tasks.
This query is a bit more complex, so let's walk through it step by step:
Identify and Specify the task_id for ClickUp task of interest.
Flatten the array with nested objects
('custom_fields')to retrieve individual objects. Add any other parameters of interest (we've added the 'name' and 'status' columns from ClickUp).
For this query, we will use the same data source referenced above and the
Get Task Data from TasksEndpoint, so piecing it all together so far we have:
We will alias this piece as
In the WHERE clause, we want to access the individual object. In this case,
namerefers to the name given to the custom field.
Identify what column we want to return data from. For ClickUp, we need to use
Use the split function on
value, delimiting on commas
,to separate the values in the nested field and create an array.
Lastly flatten the split data to generate individual rows. In our example we have aliased this as
Putting everything together this gives us the final query shown below.
SELECT `Name`, flatten(split(t1.`cf`.`value`, ',')) as `Desired Data`, t1.`status` FROM (SELECT `name` as `Name`, flatten(`custom_fields`) as cf, `status`['status'] as `status` FROM `clickupapi2000`.`Get Task Data from Tasks` WHERE task_id = 'Enter Task Id Here') as t1 WHERE t1.cf.`name` = '<Enter name of Custom Field Here>'