Skip to main content
Follow this guide to learn how to create a dataset, add data sources to the dataset, create a session associated with the dataset, and then run jobs to start anayzing the uploaded data.

​
Step 1. Get your project API key

If you’re the admin of your team, get API key of the target project on the admin console. If you’re a system user or virtual user in a team, simply ask your admin to provide you with one.

​
Step 2. Create a dataset and upload a data source to it

This step is optional but highly recommended, as it allows you to receive insights tailored to your own data.
Data sources are the data you upload to Powerdrill for embedding, indexing, knowledge extraction, and vectorized storage and retrieval, while datasets are collections of data sources that help organize and categorize them. You can create datasets and data sources in two ways:
  • Method 1: Create a dataset first, then add data sources to it.
  • Method 2: Create a data source directly without specifying a dataset, and Powerdrill will automatically create a dataset for it.
  • Method 1
  • Method 2
  1. Make a request to POST /v1/team/datasets endpoint to create a dataset. Example request: 
    curl --request POST \
  --url https://ai.data.cloud/api/v1/team/datasets \
  --header 'Content-Type: application/json' \
  --header 'x-pd-api-key: $PD_API_KEY' \
  --data '{
  "name": "My dataset",
  "description": "my default dataset",
  "userId": "tmm-cm5m7khoz52zh07n4m7x1ut60"
}'
    Replace $PD_API_KEY with the API key you’ve obtained in Step 1.
    Example response: 
    {
    "code": 0,
    "data": {
        "id": "cm3my37en3q36017q7x3hyyf4"
    }
}
    Obtain the id value (dataset ID) from the response and save it for later use.
  2. Make a request to the POST /v1/team/datasets/{datasetId}/datasources endpoint. Replace the datasetId value with the ID of the dataset you’ve created in the previous sub-step
When making the request, specify either url or fileKey, but not both. Use url to upload a file through a publicly accessible URL. For privately accessible files, use fileKey.
Example request:
curl --request POST \
  --url https://ai.data.cloud/api/v1/team/datasets/{datasetId}/datasources \
  --header 'Content-Type: application/json' \
  --header 'x-pd-api-key: $PD_API_KEY' \
  --data '{
  "name": "test.csv",
  "fileName": "test.csv",
  "type": "FILE",
  "url": "https://s3.amazonaws.com/powerdrilltest/user/clvl4cad2001q01l1m522hxlu/upload/f9773f1e-cd68-489a-8121-d566ca9218b1.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240924T143419Z&X-Amz-SignedHeaders=host&X-Amz-Expires=599&X-Amz-Credential=AKIARLSQLXURHEIDN4OZ%2F20240924%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=9ca0c58d508926a5811818041d557ffb53c64025dae94c0855280d457c7089a2",
  "userId": "tmm-cm5m7khoz52zh07n4m7x1ut60"
}'
Example response:
{
    "code": 0,
    "data": {
        "id": "cm3myfsfc03jn011csb8wah6p",
        "datasetId": "cm3my37en3q36017q7x3hyyf4",
        "name": "test.pdf",
        "fileName": "test.pdf",
        "type": "FILE",
        "status": "pending"
    }
}
Repeat this sub-step to create multiple data sources in the same dataset.

​
Step 3. Create a session

To create a session, make a request to the POST /v1/team/sessions endpoint. Sessions are essential for running jobs on Powerdrill, as each job must be linked to a session using its session ID. Example request: 
curl --request POST \
  --url https://ai.data.cloud/api/v1/team/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-pd-api-key: $PD_API_KEY' \
  --data '{
  "title": "My session",
  "languageType": "AUTO",
  "jobMode": "AUTO",
  "maxMessagesInContext": 10,
  "userId": "tmm-egejgowqg=g=egen"
}'
When making a request:
  • Replace $PD_API_KEY with the API key you’ve obtained in Step 1.
  • Set the user ID to your actual user ID.
Example response: 
{
    "code": 0,
    "data": {
        "id": "4440ab38-3df0-465b-a66c-bf6acb0f1bc2"
    }
}
Obtain the id value (session ID) from the response and save it for use in the following step.

​
Step 4. Create a job

Now, after you’ve prepared a session and probably a dataset stuffed with data sources, you can create a job to start conversing with Powerdrill.
For the definition of job, see What Is Job?.
Make a request to the POST /v1/team/jobs endpoint. Powerdrill provides the ability to stream responses, controlled by the stream parameter. For more details about how to understand the streaming mode, see Streaming.
  • If stream is set to true, streaming is enabled.
  • If stream is set to false, streaming is disabled.
  • Set stream to true:
  • Set stream to false:
Example request:
curl --request POST \
  --url https://ai.data.cloud/api/v1/team/jobs \
  --header 'Content-Type: application/json' \
  --header 'x-pd-api-key: $PD_API_KEY' \
  --data '{
"datasetId": "cm1gjmg8e0057r3x22v1fdu8m",
"datasourceIdList": [
  "cm1gjmmoo0001h0x24uk1xgu9"
],
"languageType": "EN",
"question": "Hello World",
"sessionId": "5534f591-1520-4e74-b753-b87615b2c57a",
"stream": false
}'


event:JOB_ID
data:job-cm3ik4yhz01vg01l17yk4467y

event:TITLE_GENERATION
data:test session

id:2b5cba4a-d8a5-4beb-aef9-a8612828c405
event:TASK
data:{"id":"2b5cba4a-d8a5-4beb-aef9-a8612828c405","model":"","choices":[{"delta":{"content":{"name":"Analyze","id":"2b5cba4a-d8a5-4beb-aef9-a8612828c405","status":"running","stage":"Analyze","properties":{}}},"index":0}],"created":1731664172,"groupId":"2b5cba4a-d8a5-4beb-aef9-a8612828c405","groupName":"Analyze","stage":"Analyze"}

id:2b5cba4a-d8a5-4beb-aef9-a8612828c405
event:TASK
data:{"id":"2b5cba4a-d8a5-4beb-aef9-a8612828c405","model":"","choices":[{"delta":{"content":{"name":"Analyze","id":"2b5cba4a-d8a5-4beb-aef9-a8612828c405","status":"running","stage":"Analyze","properties":{"files":""}}},"index":0}],"created":1731664172,"groupId":"2b5cba4a-d8a5-4beb-aef9-a8612828c405","groupName":"Analyze","stage":"Analyze"}

...
...
...


id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:IMAGE
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":{"url":"https://static.powerdrill.ai/tmp_datasource_cache/code_result/cm37bchx106e301l1v9yf67yc/5e3a766c-8d16-4fc0-b06f-7a337196186d.png","name":"Trends of Deaths from Different Disaster Types Over the Years","expiredAt":"2024-11-21T09:50:00.026476Z"}},"index":0}],"created":1731664200,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:MESSAGE
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":"\n\n"},"index":0}],"created":1731664200,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:MESSAGE
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":"- **Chart Description**: The chart illustrates the trend of death tolls over time for various types of disasters.\n"},"index":0}],"created":1731664200,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:MESSAGE
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":"- **Key Trends**:\n"},"index":0}],"created":1731664200,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:MESSAGE
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":"  - Droughts and floods had high death tolls in the early 20th century.\n"},"index":0}],"created":1731664200,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:MESSAGE
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":"  - Droughts and floods had higher death tolls in the early 20th century. \n"},"index":0}],"created":1731664200,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:MESSAGE
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":"  - Death tolls from other disaster types remained relatively low and stable. \n\n"},"index":0}],"created":1731664201,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:MESSAGE
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":"#### Conclusions and Insights\n"},"index":0}],"created":1731664201,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:MESSAGE
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":"- **Significant Impact of Droughts and Floods**: In the early 20th century, droughts and floods caused significantly higher death tolls compared to other disasters.\n"},"index":0}],"created":1731664201,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:MESSAGE
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":"- **Fluctuations in Earthquakes and Extreme Weather**: These disasters had significant impacts on death tolls in certain years, highlighting the need for enhanced preventive measures."},"index":0}],"created":1731664202,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:QUESTIONS
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":["Please analyze the distribution of deaths caused by different types of natural disasters across various countries and regions, and generate a corresponding ECharts map chart.","Please compare the changes in death tolls caused by natural disasters across different decades, and generate a corresponding ECharts line chart.","Please analyze the global death toll trend of a specific natural disaster (e.g., earthquakes) and generate a corresponding ECharts bar chart."]},"index":0}],"created":1731664202,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:TRIGGER
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":{"name":"conclusion_slice","arguments":{"answer":"$answer"}}},"index":0}],"created":1731664202,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3
event:TASK
data:{"id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","model":"","choices":[{"delta":{"content":{"name":"Conclusions","id":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","status":"done","stage":"Respond","properties":{}}},"index":0}],"created":1731664202,"groupId":"ccd0c9a2-b8d5-4066-8d29-2f54c87a60a3","groupName":"Conclusions","stage":"Respond"}

id:-1
event:SOURCES
data:{"id":"-1","model":"","choices":[{"delta":{"content":[{"id":"1","source":"makeovermonday-a-century-of-global-deaths-from-disasters_decadal-deaths-disasters-type.csv","datasourceId":"clxin6l9200oo01l1457bolx3","datasetId":"clxin6l8400ok01l1ff2m0s25","fileType":"csv","externalId":"clxin6l0h001901hzxhjaae6q"}]},"index":0}],"created":1731664202,"groupId":"-1","groupName":"","stage":"Analyze"}

event:END_MARK
data:[DONE]
When making a request:
  • Replace $PD_API_KEY with the API key you’ve obtained in Step 1.
  • Since this topic covers running a general job and no data agent is used, set the x-pd-api-agent-id header to GENERAL (uppercase).
  • Replace the sessionId value with the ID of the session you’ve created in Step 3.
  • To enable Powerdrill to retrieve information from your own data and provide responses specific to it, set the datasetId to the ID of the dataset obtained in Step 2.
⌘I