Powerdrill Enterprise Open API supports streaming responses to clients, enabling partial results for specific requests. This functionality is implemented using the Server-Sent Events (SSE) standard.

​
How to understand streaming responses

The response to each request consists of a series of response blocks. When streaming mode is enabled for a request, Powerdrill will send real-time updates to the client, delivering continuous response blocks as they becomes available. The structure of a response block is as follows: 
{
    "id": "<group_id>",
    "model": "",
    "choices": [
        {
            "delta": {
                "content": "<content>"
            },
            "index": 0
        }
    ],
    "created": 1731664172,
    "group_id": "<group_id>",
    "group_name": "<group_name>",
    "stage": "<block_stage>"
}
Each streaming response block contains the following fields:
  • id and group_id: The ID of the group to which the response block belongs. A group in the streaming response is a collection of response blocks. For example, in a general job, each step in the Analyze stage is a group, and the entire Respond stage is a group.
  • content: The content of the response block, which varies with the block type. For more details, see Content description.
  • created: The timestamp indicating when the content was created.
  • group_id: The ID of the group to which the response block belongs.
  • group_name: The name of the group, such as Conclusions.
  • stage: The stage to which the response block belongs. Two stages are available: Analyze and Respond.
When you encounter :keep-alive in a response, simply ignore it—it serves only as a heartbeat signal to maintain the connection.

​
Content description

The value of content in each response block varies with the block content type:
  • When the block content type is MESSAGE: The content is a piece of text.
  • When the block content type is CODE: The content is a code snippet in Markdown format.
  • When the block content type is TABLE: The content represents a table, consisting of:
    • name: The .csv file name.
    • url: The S3 key or URL to the file.
    • expires_at: The expiration time for url. To save the table for future use, make sure to download it before it expires.
  • When the block content type is IMAGE: The content represents an image, consisting of:
    • name: The image name.
    • url: The S3 key or URL to the image.
    • expires_at: The expiration time for url. To save the image for future use, make sure to download it before it expires.
  • When the block content type is SOURCES: The content represents the source of the response block, including:
    • id: The ID of the source.
    • content: The chunk content.
    • page_no: The location of the chunk in the source file.
    • source: The file name of the data source.
    • datasource_id: The ID of the data source.
    • dataset_id: The ID of the dataset.
    • file_type: The name extension of the data source file.
  • When the block content type is QUESTIONS: The content represents follow-up questions suggested by Powerdrill.
Let’s see an example.
For details about the POST /v2/jobs endpoint, see Create job.
Python request
import requests

url = "https://ai.data.cloud/api/v2/team/jobs"

payload = {
    "session_id": "cxxdgegeegeg3433fff",
    "user_id": "tmm-dafasdfasdfasdf",
    "stream": True,
    "question": "Which travel agency has the highest average booking price?",
    "dataset_id": "cm1gjmg8e0057r3x22v1fdu8m",
    "datasource_ids": ["cm1gjmmoo0001h0x24uk1xgu9"],
    "output_language": "AUTO",
    "job_mode": "AUTO"
}
headers = {
    "x-pd-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)
The response is simlilar to this:
However, if streaming is disabled, Powerdrill returns the response only after the entire response is ready. Let’s use the same request as an example for a clear comparison. The only difference is that stream is set to False. 
import requests

url = "https://ai.data.cloud/api/v2/team/jobs"

payload = {
    "session_id": "cxxdgegeegeg3433fff",
    "user_id": "tmm-dafasdfasdfasdf",
    "stream": False,
    "question": "Which travel agency has the highest average booking price?",
    "dataset_id": "cm1gjmg8e0057r3x22v1fdu8m",
    "datasource_ids": ["cm1gjmmoo0001h0x24uk1xgu9"],
    "output_language": "EN",
    "job_mode": "AUTO"
}
headers = {
    "x-pd-api-key": "$PROJECT_API_KEY",
    "Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)
The response looks like this:

​
Need more help?

Post to our help community

Get answers from our members

Contact us

Tell us more and we’ll help you out