Jobs

How to use the Jobs API

The Jobs API enables you to execute Agents created in Upstage Studio. By submitting files to an Agent, you can automate complex document processing workflows.

To run a job, you need the following:

File IDs: Upload your documents via the Files API to obtain file_ids.
Agent ID: Specify the target Agent by passing its agent_id in the model parameter.

You can find your Agent's ID in the Upstage Studio console by navigating to the Agent's page and clicking the Code button. For detailed instructions, refer to Get an Agent ID in Studio.

Create Job

Request

from openai import OpenAI
from time import sleep
import json
 
client = OpenAI(
    api_key="UPSTAGE_API_KEY",
    base_url="https://api.upstage.ai/v2"
)

# Supports multiple files
input_files = [
    {
        "type": "input_file",
        "file_id": "file-abc123"
    }
]
 
input = [
    {
        "role": "user",
        "content": [
            *input_files
        ]
    }
]
 
# Create a job
resp = client.responses.create(
    model="agt_BxcRatEWzVYH2yRNtyWynn",
    include=["last"],
    input=input,
)
 
# Poll until the job is no longer queued or in progress
while resp.status in {"queued", "in_progress"}:
    sleep(2)
    resp = client.responses.retrieve(
        resp.id,
        include=["last"]
    )

# When completed, read the final output text
if resp.status == "completed":
    print(json.loads(resp.output_text))

Response

{
  "id": "job_7yMqwGy3rfh6Pwo7MdseMo",
  "object": "response",
  "created_at": 1767613535,
  "status": "completed",
  "background": true,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "agt_BxcRatEWzVYH2yRNtyWynn",
  "output": [
    {
      "id": "fb543069-1a45-4fde-94de-2383995d7339",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "model": "step_2_extract",
      "content": [
        {
          "type": "output_text",
          "text": "{\"key\": \"value\", \"group_key\": [{\"properties\": \"properties_value\"}]}",
          "annotations": [],
          "additional_values": "{...}"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0
  }
}

How to get a job result

An Agent executes a workflow that may consist of multiple steps, such as Parse, Classify, and Extract. The structure of the job result reflects this multi-step process.

The response contains an output field, which is a list where each element represents the result of a specific step in the workflow. The structure of each step's result mirrors the output of its corresponding standalone API:

Control the output range with `include`

User can want to access the result of only the latest step or the full step history. They can use include parameter to control how much of the step history is returned:

include value	Behavior
`last` (default)	Returns only the result of the final step.
`all`	Returns the results of all steps in the order they were executed.

Retrieve Job

Request

from openai import OpenAI
 
client = OpenAI(
    api_key="UPSTAGE_API_KEY",
    base_url="https://api.upstage.ai/v2"
)

response = client.responses.retrieve(
    job_id,
    include=["all"]
)
print(response.model_dump())

Response

{
  "id": "job_7yMqwGy3rfh6Pwo7MdseMo",
  "object": "response",
  "created_at": 1767613535,
  "status": "completed",
  "background": true,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "agt_BxcRatEWzVYH2yRNtyWynn",
  "output": [
    {
      "id": "e2e14327-740c-40d2-b353-fda754b8e0d8",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "model": "step_1_parse",
      "content": [
        {
          "type": "output_text",
          "text": "{\"api\": \"2.0\", \"content\": {\"html\": \"...\"}}",
          "annotations": [],
          "additional_values": "{\"document_ids\": [\"file-abc123\"]}"
        }
      ]
    },
    {
      "id": "fb543069-1a45-4fde-94de-2383995d7339",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "model": "step_2_extract",
      "content": [
        {
          "type": "output_text",
          "text": "{\"key\": \"value\", \"group_key\": [{\"properties\": \"properties_value\"}]}",
          "annotations": [],
          "additional_values": "{...}"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0
  }
}

How to parse the result

Access the result via `output_text`

To quickly access the final result of the job, use the retrieve method with include=["last"]. The primary output text will be available in the response.output_text field.

from openai import OpenAI

client = OpenAI(
    api_key="UPSTAGE_API_KEY",
    base_url="https://api.upstage.ai/v2"
)

response = client.responses.retrieve(
    job_id="job_7yMqwGy3rfh6Pwo7MdseMo",
    include=["last"]
)
print(response.output_text)

Parse `additional_values`

For each step:

content[].text contains the main result, which matches the corresponding API’s primary output (for example, extraction result of Information Extract API).
content[].additional_values contains the additional result, which matches the corresponding API’s extra payload (for example, confidence or location values of Information Extract API).

Note: The additional_values field is returned as a stringified JSON object. You must parse it (e.g., using json.loads in Python) to access the underlying data structure.

import json
from openai import OpenAI

client = OpenAI(
    api_key="UPSTAGE_API_KEY",
    base_url="https://api.upstage.ai/v2"
)

response = client.responses.retrieve(
    job_id="job_7yMqwGy3rfh6Pwo7MdseMo",
    include=["last"]
)

for step in response.output:
    for item in step.get("content", []):
        additional_values = item.get("additional_values")
        if additional_values:
            # Parse the stringified JSON
            print(json.loads(additional_values))

Jobs

How to use the Jobs API

The Jobs API enables you to execute Agents created in Upstage Studio. By submitting files to an Agent, you can automate complex document processing workflows.

To run a job, you need the following:

File IDs: Upload your documents via the Files API to obtain file_ids.
Agent ID: Specify the target Agent by passing its agent_id in the model parameter.

You can find your Agent's ID in the Upstage Studio console by navigating to the Agent's page and clicking the Code button. For detailed instructions, refer to Get an Agent ID in Studio.

Create Job

Request

from openai import OpenAI
from time import sleep
import json
 
client = OpenAI(
    api_key="UPSTAGE_API_KEY",
    base_url="https://api.upstage.ai/v2"
)

# Supports multiple files
input_files = [
    {
        "type": "input_file",
        "file_id": "file-abc123"
    }
]
 
input = [
    {
        "role": "user",
        "content": [
            *input_files
        ]
    }
]
 
# Create a job
resp = client.responses.create(
    model="agt_BxcRatEWzVYH2yRNtyWynn",
    include=["last"],
    input=input,
)
 
# Poll until the job is no longer queued or in progress
while resp.status in {"queued", "in_progress"}:
    sleep(2)
    resp = client.responses.retrieve(
        resp.id,
        include=["last"]
    )

# When completed, read the final output text
if resp.status == "completed":
    print(json.loads(resp.output_text))

Response

{
  "id": "job_7yMqwGy3rfh6Pwo7MdseMo",
  "object": "response",
  "created_at": 1767613535,
  "status": "completed",
  "background": true,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "agt_BxcRatEWzVYH2yRNtyWynn",
  "output": [
    {
      "id": "fb543069-1a45-4fde-94de-2383995d7339",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "model": "step_2_extract",
      "content": [
        {
          "type": "output_text",
          "text": "{\"key\": \"value\", \"group_key\": [{\"properties\": \"properties_value\"}]}",
          "annotations": [],
          "additional_values": "{...}"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0
  }
}

How to get a job result

An Agent executes a workflow that may consist of multiple steps, such as Parse, Classify, and Extract. The structure of the job result reflects this multi-step process.

Output Structure

Control the output range with `include`

User can want to access the result of only the latest step or the full step history. They can use include parameter to control how much of the step history is returned:

include value	Behavior
`last` (default)	Returns only the result of the final step.
`all`	Returns the results of all steps in the order they were executed.

Retrieve Job

Request

from openai import OpenAI
 
client = OpenAI(
    api_key="UPSTAGE_API_KEY",
    base_url="https://api.upstage.ai/v2"
)

response = client.responses.retrieve(
    job_id,
    include=["all"]
)
print(response.model_dump())

Response

{
  "id": "job_7yMqwGy3rfh6Pwo7MdseMo",
  "object": "response",
  "created_at": 1767613535,
  "status": "completed",
  "background": true,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "agt_BxcRatEWzVYH2yRNtyWynn",
  "output": [
    {
      "id": "e2e14327-740c-40d2-b353-fda754b8e0d8",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "model": "step_1_parse",
      "content": [
        {
          "type": "output_text",
          "text": "{\"api\": \"2.0\", \"content\": {\"html\": \"...\"}}",
          "annotations": [],
          "additional_values": "{\"document_ids\": [\"file-abc123\"]}"
        }
      ]
    },
    {
      "id": "fb543069-1a45-4fde-94de-2383995d7339",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "model": "step_2_extract",
      "content": [
        {
          "type": "output_text",
          "text": "{\"key\": \"value\", \"group_key\": [{\"properties\": \"properties_value\"}]}",
          "annotations": [],
          "additional_values": "{...}"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0
  }
}

How to parse the result

Access the result via `output_text`

To quickly access the final result of the job, use the retrieve method with include=["last"]. The primary output text will be available in the response.output_text field.

from openai import OpenAI

client = OpenAI(
    api_key="UPSTAGE_API_KEY",
    base_url="https://api.upstage.ai/v2"
)

response = client.responses.retrieve(
    job_id="job_7yMqwGy3rfh6Pwo7MdseMo",
    include=["last"]
)
print(response.output_text)

Parse `additional_values`

For each step:

content[].text contains the main result, which matches the corresponding API’s primary output (for example, extraction result of Information Extract API).
content[].additional_values contains the additional result, which matches the corresponding API’s extra payload (for example, confidence or location values of Information Extract API).

Note: The additional_values field is returned as a stringified JSON object. You must parse it (e.g., using json.loads in Python) to access the underlying data structure.

import json
from openai import OpenAI

client = OpenAI(
    api_key="UPSTAGE_API_KEY",
    base_url="https://api.upstage.ai/v2"
)

response = client.responses.retrieve(
    job_id="job_7yMqwGy3rfh6Pwo7MdseMo",
    include=["last"]
)

for step in response.output:
    for item in step.get("content", []):
        additional_values = item.get("additional_values")
        if additional_values:
            # Parse the stringified JSON
            print(json.loads(additional_values))

Jobs

How to use the Jobs API

Create Job

Response

How to get a job result

Output Structure

Control the output range with `include`

Retrieve Job

Response

How to parse the result

Access the result via `output_text`

Parse `additional_values`

On this page

Jobs

How to use the Jobs API

Create Job

Response

How to get a job result

Output Structure

Control the output range with `include`

Retrieve Job

Response

How to parse the result

Access the result via `output_text`

Parse `additional_values`

On this page