Skip to Content
API DocumentationStreaming

Streaming

MAXIR AI Open API supports sending streaming responses to clients, providing partial results for specific requests. This feature is implemented through the Server-Sent Events (SSE)  standard.

Understanding Streaming Responses

The response for each request consists of a series of response blocks. When streaming mode is enabled for a request, MAXIR AI sends updates to the client in real-time, continuously delivering response blocks until all data is fully returned.

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.

    Groups in streaming responses are collections of response blocks. For example, in a typical task, each step of the Analyze stage is one group, and the entire Respond stage is another group.

  • content: The content of the response block, which varies depending on the block’s 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. There are two stages: Analyze and Respond.

Content Description

The value of content in each response block varies depending on the block’s content type:

  • When the block’s content type is MESSAGE:

    The content is a piece of text.

  • When the block’s content type is CODE:

    The content is a code snippet in Markdown format.

  • When the block’s content type is TABLE:

    The content represents a table and includes:

    • name: The .csv file name.

    • url: The S3 key or URL of the file.

    • expired_at: The expiration date of the url. To keep the table for future use, ensure it is downloaded before expiry.

  • When the block’s content type is IMAGE:

    The content represents an image and includes:

    • name: The name of the image.

    • url: The S3 key or URL of the image.

    • expired_at: The expiration date of the url. To keep the image for future use, ensure it is downloaded before expiry.

  • When the block’s content type is SOURCES:

    The content represents the sources of the response block and includes:

    • 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 extension of the data source file.

  • When the block’s content type is QUESTIONS:

    The content represents subsequent questions prompted by the MAXIR AI.

Let us look at an example.

For detailed information on the POST /v2/jobs endpoint, see Create Job.

import requests
 
url = "http://<domain_name>/app/api/v2/team/jobs"
 
payload = {
    "session_id": "cxxdgegeegeg3433fff",
    "user_id": "tmm-dafasdfasdfasdf",
    "stream": True,
    "question": "Among the combinations of departure city and arrival city, which pair is the most common",
    "dataset_id": "cm1gjmg8e0057r3x22v1fdu8m",
    "datasource_ids": ["cm1gjmmoo0001h0x24uk1xgu9"],
    "output_language": "ZH-CN",
    "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)

Here is an example of a response [Streaming Response]:

event:JOB_ID
data:job-cm7391oea00cb01l1auht64zg

id:a928b4fd-39b3-4da3-af21-43b4469cc3b8
event:TASK
data:{"id":"a928b4fd-39b3-4da3-af21-43b4469cc3b8","model":"","choices":[{"delta":{"content":{"name":"Analyzing","id":"a928b4fd-39b3-4da3-af21-43b4469cc3b8","status":"running","parent_id":null,"stage":"Analyze","properties":{}}},"index":0,"finish_reason":null}],"created":1739445679,"group_id":"a928b4fd-39b3-4da3-af21-43b4469cc3b8","group_name":"Analyzing","stage":"Analyze"}

id:a928b4fd-39b3-4da3-af21-43b4469cc3b8
event:TASK
data:{"id":"a928b4fd-39b3-4da3-af21-43b4469cc3b8","model":"","choices":[{"delta":{"content":{"name":"Analyzing","id":"a928b4fd-39b3-4da3-af21-43b4469cc3b8","status":"running","parent_id":null,"stage":"Analyze","properties":{"files":""}}},"index":0,"finish_reason":null}],"created":1739445680,"group_id":"a928b4fd-39b3-4da3-af21-43b4469cc3b8","group_name":"Analyzing","stage":"Analyze"}

id:a928b4fd-39b3-4da3-af21-43b4469cc3b8
event:TASK
data:{"id":"a928b4fd-39b3-4da3-af21-43b4469cc3b8","model":"","choices":[{"delta":{"content":{"name":"Analyzing","id":"a928b4fd-39b3-4da3-af21-43b4469cc3b8","status":"done","parent_id":null,"stage":"Analyze","properties":{"files":""}}},"index":0,"finish_reason":null}],"created":1739445680,"group_id":"a928b4fd-39b3-4da3-af21-43b4469cc3b8","group_name":"Analyzing","stage":"Analyze"}

...

If streaming is not enabled, MAXIR AI only returns responses when the entire response is ready.

Let’s compare with the same request for clarity. The only difference is setting stream to False.

import requests
 
url = "https://<domain_name>/app/api/v2/team/jobs"
 
payload = {
    "session_id": "cxxdgegeegeg3433fff",
    "user_id": "tmm-dafasdfasdfasdf",
    "stream": False,
    "question": "Among the combinations of departure city and arrival city, which pair is the most common?",
    "dataset_id": "cm1gjmg8e0057r3x22v1fdu8m",
    "datasource_ids": ["cm1gjmmoo0001h0x24uk1xgu9"],
    "output_language": "ZH-CN",
    "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)

Here is an example of a response [Non-Streaming Response]:

{"code":0,"msg":null,"data":{"job_id":"job-cm738zrbt00bv01l13uy02cdk","blocks":[{"type":"CODE","content":"```python\n\nimport pandas as pd\n\ndef invoke(input_0: pd.DataFrame) -> pd.DataFrame:\n    # Group by the combination of departure and arrival cities and count occurrences\n    city_combinations = input_0.groupby(['出发城市(城市三字码)', '到达城市(城市三字码)']).size().reset_index(name='组合出现次数')\n    \n    # Sort the combinations by the count in descending order to find the most common ones\n    city_combinations_sorted = city_combinations.sort_values(by='组合出现次数', ascending=False).reset_index(drop=True)\n    \n    # Assign the result to the output variable\n    output = city_combinations_sorted\n    \n    return output\n\n```","group_id":"327b3b90-c947-4efb-be74-845b6edf29e2","group_name":"Analyzing data of departure city (city code) and arrival city (city code) combinations, counting occurrences of each pair to find the most common combination.","stage":"Analyze"},{"type":"TABLE","content":{"url":"https://static.xxx.ai/tmp_datasource_cache/code_result/tmm-cm5ao3yoe00zm01l1u1e7p3pj/e8a4d119-edc1-4877-a8e4-379ca9a99dc6.csv","name":"city_combination_data.csv","expired_at":"2025-02-13T11:30:15.453397Z"},"group_id":"327b3b90-c947-4efb-be74-845b6edf29e2","group_name":"Analyzing data of departure city (city code) and arrival city (city code) combinations, counting occurrences of each pair to find the most common combination.","stage":"Analyze"},{"type":"CODE","content":"```python\n\nimport pandas as pd\nimport matplotlib.pyplot as plt\nimport io\n\ndef invoke(city_combination_data: pd.DataFrame) -> io.BytesIO:\n    # Sort the data by '组合出现次数' in descending order and take the top 100\n    top_combinations = city_combination_data.sort_values(by='组合出现次数', ascending=False).head(100)\n    \n    # Create a new column for the city combination\n    top_combinations['城市组合'] = top_combinations['出发城市(城市三字码)'] + '-' + top_combinations['到达城市(城市三字码)']\n    \n    # Plotting\n    fig, ax = plt.subplots(figsize=(12, 8))\n    ax.bar(top_combinations['城市组合'], top_combinations['组合出现次数'])\n    \n    # Set labels and title\n    ax.set_xlabel('城市组合')\n    ax.set_ylabel('组合出现次数')\n    ax.set_title('Most Common City Combination Frequencies')\n    \n    # Rotate x-axis labels for better readability\n    plt.xticks(rotation=90)\n    \n    # Use tight layout for better spacing\n    plt.tight_layout()\n    \n    # Save the plot to a BytesIO object\n    output = io.BytesIO()\n    plt.savefig(output, format='png')\n    plt.close(fig)\n    \n    # Seek to the beginning of the BytesIO object\n    output.seek(0)\n    \n    return output\n\n```","group_id":"f443de5b-1960-42be-bef8-3c4d4c5c011e","group_name":"Visualizing the frequency of city combinations using a bar chart to show the most common city combinations.","stage":"Analyze"},{"type":"IMAGE","content":{"url":"https://static.xxx.ai/tmp_datasource_cache/code_result/tmm-cm5ao3yoe00zm01l1u1e7p3pj/30c8fa22-d666-4e82-8682-352b8dc1982d.png","name":"visualization.png","expired_at":"2025-02-13T11:30:15.453397Z"},"group_id":"f443de5b-1960-42be-bef8-3c4d4c5c011e","group_name":"Visualizing the frequency of city combinations using a bar chart to show the most common city combinations.","stage":"Analyze"},{"type":"MESSAGE","content":"\n\n`Analyzing Conclusions` \n\n### Most Common City Combinations\n\n#### Data Analysis\n\n","group_id":"2ddd5382-f302-4f33-917e-124d9c925eab","group_name":"Conclusions","stage":"Respond"},{"type":"TABLE","content":{"url":"https://static.xxx.ai/tmp_datasource_cache/code_result/tmm-cm5ao3yoe00zm01l1u1e7p3pj/e8a4d119-edc1-4877-a8e4-379ca9a99dc6.csv","name":"city_combination_data.csv","expired_at":"2025-02-13T11:30:15.453397Z"},"group_id":"2ddd5382-f302-4f33-917e-124d9c925eab","group_name":"Conclusions","stage":"Respond"},{"type":"MESSAGE","content":"\n\n- **Most Common Pair**: The most common pair is departing from BKK and arriving at HKT, occurring 116 times.\n- **Other High-Frequency Pairs**: HKT to BKK occurs 99 times, TYO to SPK occurs 86 times, CNX to BKK occurs 76 times, and BKK to CNX occurs 73 times.\n\n#### Visualization Analysis\n\n","group_id":"2ddd5382-f302-4f33-917e-124d9c925eab","group_name":"Conclusions","stage":"Respond"},{"type":"IMAGE","content":{"url":"https://static.xxx.ai/tmp_datasource_cache/code_result/tmm-cm5ao3yoe00zm01l1u1e7p3pj/30c8fa22-d666-4e82-8682-352b8dc1982d.png","name":"visualization.png","expired_at":"2025-02-13T11:30:15.453397Z"},"group_id":"2ddd5382-f302-4f33-917e-124d9c925eab","group_name":"Conclusions","stage":"Respond"},{"type":"MESSAGE","content":"\n\n- **Bar Chart Visualization**: The chart shows the frequency of each city combination, with the BKK to HKT combination significantly higher than others.\n\n#### Conclusions and Insights\n- **Most Common City Combination**: BKK to HKT is the most common city combination.\n- **High Frequency Routes**: These high-frequency combinations might reflect popular flight routes or trends in tourist destinations.","group_id":"2ddd5382-f302-4f33-917e-124d9c925eab","group_name":"Conclusions","stage":"Respond"},{"type":"SOURCES","content":[{"source":"junlan.csv","datasource_id":"ds-cm5clulg2000101fcumw33r4k","dataset_id":"dset-cm5clulda02s401l133osoja3","file_type":"csv","external_id":"4444"}],"group_id":"","group_name":"","stage":"Respond"},{"type":"QUESTIONS","content":["Analyze the trend of departure city and arrival city combinations, whether there is a significant difference on different dates.","Explore the relationship between departure and arrival city combinations and airline names, whether certain airlines tend towards specific city combinations.","Study the correlation between city combinations and ticket issuance and baggage counts, whether certain combinations lead to higher ticket or baggage numbers."],"group_id":"-1","group_name":null,"stage":"Respond"}]}}
AuthenticationError Codes