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.

​
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.

    • expired_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.

    • expired_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:

    • 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: