> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/openai.md).

# OpenAI

OpenAI provides advanced AI models including GPT-4, DALL-E, and Whisper with support for chat completions, assistants, threads, and the new unified Responses API for multimodal interactions.

### Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector    | Authentication |
| ------------ | -------------- |
| OpenAI       | API Key        |
| OpenAI Admin | Admin API Key  |

#### OpenAI

Connect to OpenAI's API to access GPT models, ChatGPT, DALL-E, Whisper, and other AI capabilities.

**Set up in OpenAI**

1. Sign in to the OpenAI platform at <https://platform.openai.com> and add a payment method under Billing (required before keys will work).
2. Open the API keys page at <https://platform.openai.com/api-keys>.
3. Click **Create new secret key**, name it, and choose the permission scope you want.
4. Copy the key immediately and store it securely; it is shown only once.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **OpenAI**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field | Required | What to enter                                                                                                         |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| API Key       | Yes      | Your OpenAI API key from your OpenAI account settings. [Provider instructions](https://platform.openai.com/api-keys). |

**Provider documentation:** [Setup reference](https://platform.openai.com/api-keys).

#### OpenAI Admin

Read OpenAI organization cost and token usage with an Admin API key. Separate from the standard OpenAI connection, which cannot access organization billing.

**Set up in OpenAI**

1. Prepare the OpenAI account or service that the workflow will access. Grant access to the required resources and operations.
2. **Admin API Key:** An OpenAI Admin API key, which starts with `sk-admin`. Create one in the platform settings under Organization, Admin keys. This is NOT a project API key: a project key cannot read organization cost or usage and is rejected here. An admin key can read spend across the whole organization, so treat it as a high-privilege secret.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **OpenAI Admin**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field | Required | What to enter                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Admin API Key | Yes      | An OpenAI Admin API key, which starts with `sk-admin`. Create one in the platform settings under Organization, Admin keys. This is NOT a project API key: a project key cannot read organization cost or usage and is rejected here. An admin key can read spend across the whole organization, so treat it as a high-privilege secret. [Provider instructions](https://platform.openai.com/settings/organization/admin-keys). |

#### Verify the connection

Check that the connection is healthy, then verify access with a read operation:

For a standard **OpenAI** connection, run **List Assistants** and inspect the returned list. An empty list is valid when the project has no assistants. This read operation does not generate model output.

For an **OpenAI Admin** connection, run **List Projects** with **Maximum Pages** set to 1. Inspect **Projects** and **Total Count**. This checks organization-level access and does not validate the standard project's model permissions.

A successful connection check confirms authentication. It does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

### Use an action

1. Add the required **OpenAI** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

### Actions

#### Create Chat Completion

Create a chat completion using OpenAI's Chat API with support for conversations, function calling, and advanced generation parameters.

**Inputs**

| Field        | Type   | Required | Description                                                                               |
| ------------ | ------ | -------- | ----------------------------------------------------------------------------------------- |
| Request Body | object | Yes      | Configuration for the chat completion including messages, model, and generation settings. |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### List Chat Completions

List stored chat completions. Only chat completions that were created with the 'store' parameter set to true will be returned.

**Inputs**

| Field    | Type    | Required | Description                                                                 |
| -------- | ------- | -------- | --------------------------------------------------------------------------- |
| Model    | string  | No       | Filter by the model used to generate completions.                           |
| Metadata | dict    | No       | Metadata filters to apply when listing completions.                         |
| After    | string  | No       | Cursor for pagination - ID of the last completion from previous page.       |
| Limit    | integer | No       | Maximum number of completions to return per page. Minimum: 1. Maximum: 100. |
| Order    | string  | No       | Sort order for results (asc or desc).                                       |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Get Chat Completion

Get a specific stored chat completion by its ID. Only chat completions that were created with the 'store' parameter set to true can be retrieved.

**Inputs**

| Field         | Type   | Required | Description                                            |
| ------------- | ------ | -------- | ------------------------------------------------------ |
| Completion ID | string | Yes      | The unique identifier of the chat completion to fetch. |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Update Chat Completion

Update a stored chat completion's metadata. Only chat completions that were created with created with 'store': true can be updated. If you get a 'Server overloaded' error, the completion was likely not stored during creation.

**Inputs**

| Field         | Type   | Required | Description                                             |
| ------------- | ------ | -------- | ------------------------------------------------------- |
| Completion ID | string | Yes      | The unique identifier of the chat completion to modify. |
| Request Body  | object | Yes      | The metadata to update on the chat completion.          |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Delete Chat Completion

Delete a stored chat completion. Only chat completions that were created with the 'store' parameter set to true can be deleted.

**Inputs**

| Field         | Type   | Required | Description                                             |
| ------------- | ------ | -------- | ------------------------------------------------------- |
| Completion ID | string | Yes      | The unique identifier of the chat completion to remove. |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Get Chat Completion Messages

Get the messages from a stored chat completion. Only chat completions that were created with the 'store' parameter set to true will have accessible messages.

**Inputs**

| Field         | Type    | Required | Description                                                              |
| ------------- | ------- | -------- | ------------------------------------------------------------------------ |
| Completion ID | string  | Yes      | The unique identifier of the chat completion to get messages for.        |
| After         | string  | No       | Cursor for pagination - ID of the last message from previous page.       |
| Limit         | integer | No       | Maximum number of messages to return per page. Minimum: 1. Maximum: 100. |
| Order         | string  | No       | Sort order for results (asc or desc).                                    |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### List Assistants

Returns a list of assistants from OpenAI.

**Inputs**

| Field  | Type   | Required | Description                                                                                                                                       |
| ------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Limit  | number | No       | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. Minimum: 1. Maximum: 100. Default: 20. |
| Order  | string | No       | Sort order by the created\_at timestamp of the objects. asc for ascending order and desc for descending order. Default: desc.                     |
| After  | string | No       | A cursor for use in pagination. after is an object ID that defines your place in the list.                                                        |
| Before | string | No       | A cursor for use in pagination. before is an object ID that defines your place in the list.                                                       |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Create Assistant

Create a new OpenAI assistant with specified configuration.

**Inputs**

| Field        | Type   | Required | Description                                                                                |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------ |
| Request Body | object | Yes      | Configuration for the new OpenAI assistant including model, name, instructions, and tools. |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Get Assistant

Retrieve a specific OpenAI assistant by its ID.

**Inputs**

| Field        | Type   | Required | Description                                         |
| ------------ | ------ | -------- | --------------------------------------------------- |
| Assistant ID | string | Yes      | The unique identifier of the assistant to retrieve. |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Modify Assistant

Modify an existing OpenAI assistant's configuration.

**Inputs**

| Field        | Type   | Required | Description                                                                                    |
| ------------ | ------ | -------- | ---------------------------------------------------------------------------------------------- |
| Assistant ID | string | Yes      | The unique identifier of the assistant to modify.                                              |
| Request Body | object | Yes      | Updated configuration for the OpenAI assistant including model, name, instructions, and tools. |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Delete Assistant

Delete an OpenAI assistant permanently.

**Inputs**

| Field        | Type   | Required | Description                                                   |
| ------------ | ------ | -------- | ------------------------------------------------------------- |
| Assistant ID | string | Yes      | The unique identifier of the assistant to delete permanently. |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Create Thread

Create a new OpenAI thread for organizing a conversation between an assistant and users.

**Inputs**

| Field        | Type   | Required | Description                                                                               |
| ------------ | ------ | -------- | ----------------------------------------------------------------------------------------- |
| Request Body | object | Yes      | Configuration for the new OpenAI thread including optional initial messages and metadata. |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Get Thread

Retrieve a specific OpenAI thread by its ID to see its configuration and metadata.

**Inputs**

| Field     | Type   | Required | Description                                          |
| --------- | ------ | -------- | ---------------------------------------------------- |
| Thread ID | string | Yes      | The unique identifier of the thread you want to get. |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Modify Thread

Modify a specific OpenAI thread's metadata and tool resources by its ID.

**Inputs**

| Field        | Type   | Required | Description                                                    |
| ------------ | ------ | -------- | -------------------------------------------------------------- |
| Thread ID    | string | Yes      | The unique identifier of the thread you want to update.        |
| Request Body | object | Yes      | Parameters needed to update a specific thread's configuration. |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Delete Thread

Delete a specific OpenAI thread by its ID to permanently remove it and all its messages.

**Inputs**

| Field     | Type   | Required | Description                                             |
| --------- | ------ | -------- | ------------------------------------------------------- |
| Thread ID | string | Yes      | The unique identifier of the thread you want to delete. |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Create Response

Create a response using OpenAI's unified Responses API with support for multimodal inputs, web search, file search, function calling, and stateful conversations.

**Inputs**

| Field        | Type   | Required | Description                                                                                                |
| ------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------------- |
| Request Body | object | Yes      | Configuration for the response including input, model selection, available tools, and generation settings. |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Get Response

Retrieve a previously created response from OpenAI's Responses API by its unique ID.

**Inputs**

| Field       | Type   | Required | Description                                  |
| ----------- | ------ | -------- | -------------------------------------------- |
| Response ID | string | Yes      | The ID of the response you want to retrieve. |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Delete Response

Delete a stored response from OpenAI's Responses API to free up storage and remove data.

**Inputs**

| Field       | Type   | Required | Description                                |
| ----------- | ------ | -------- | ------------------------------------------ |
| Response ID | string | Yes      | The ID of the response you want to delete. |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Cancel Response

Cancel an in-progress background response from OpenAI's Responses API.

**Inputs**

| Field       | Type   | Required | Description                                |
| ----------- | ------ | -------- | ------------------------------------------ |
| Response ID | string | Yes      | The ID of the response you want to cancel. |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Edit Image

Edit images using OpenAI's image editing capabilities. Upload an image and describe the changes you want to make. The edited image will be automatically uploaded to your storage.

**Inputs**

| Field        | Type   | Required | Description                                                                                      |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------ |
| Request Body | object | Yes      | Configuration for image editing including source image, editing prompt, and generation settings. |

**Outputs**

| Field       | Type    | Description                  |
| ----------- | ------- | ---------------------------- |
| Status Code | integer | Status code of the response. |
| Headers     | dict    | Headers of the response.     |
| Body        | object  | Body of the response.        |

#### Get Cost Report

Read what your OpenAI organization spent over a date range, optionally broken down by project, line item or API key.

**Inputs**

| Field         | Type            | Required | Description                                                                                                                                                                          |
| ------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Date Range    | select (string) | No       | Pick a preset window, or choose 'custom' and set Start Date and End Date. The cost report covers up to 180 days. Options load from the selected connection. Default: last\_30\_days. |
| Start Date    | string          | No       | First UTC day to include (YYYY-MM-DD). Needed for 'custom'.                                                                                                                          |
| End Date      | string          | No       | Last UTC day to include (YYYY-MM-DD). This day is included. Needed for 'custom'.                                                                                                     |
| Group By      | select (string) | No       | Break the cost down by project, by line item, or by API key. Leave empty for daily totals only. Options load from the selected connection.                                           |
| Projects      | select (string) | No       | Limit the report to specific projects. Leave empty for all. Options load from the selected connection.                                                                               |
| Maximum Pages | integer         | No       | How many result pages to fetch before stopping.                                                                                                                                      |
| Start Cursor  | string          | No       | Resume a report that was cut short: pass the Next Cursor from the previous run.                                                                                                      |

**Outputs**

| Field             | Type    | Description                                                                                                                                    |
| ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Total Cost        | number  | Total spend across the buckets returned, in the currency reported alongside it. Check Covers Full Range before reading it as the whole period. |
| Currency          | string  | Currency of the amounts, as reported by OpenAI.                                                                                                |
| Buckets           | array   | One entry per day, with its total and its cost lines.                                                                                          |
| Start Date        | string  | Inclusive start of the range covered (ISO 8601 UTC).                                                                                           |
| End Date          | string  | Exclusive end of the range covered (ISO 8601 UTC).                                                                                             |
| Next Cursor       | string  | Pass this back as Start Cursor to continue where this stopped.                                                                                 |
| Truncated         | boolean | True when more pages were available than were fetched.                                                                                         |
| Covers Full Range | boolean | True when the numbers below cover the whole date range that was asked for.                                                                     |

#### Get Usage Report

Read OpenAI usage over a date range for any surface: completions, embeddings, images, audio, moderations, vector stores or tool calls.

**Inputs**

| Field         | Type            | Required | Description                                                                                                                                                                                                   |
| ------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Usage Type    | select (string) | No       | Which usage surface to report on. Completions covers the language models and is where most spend sits. Options load from the selected connection. Default: completions.                                       |
| Date Range    | select (string) | No       | Pick a preset window, or choose 'custom' and set Start Date and End Date. Usage reports cover at most 31 days of daily buckets. Options load from the selected connection. Default: last\_7\_days.            |
| Start Date    | string          | No       | First UTC day to include (YYYY-MM-DD). Needed for 'custom'.                                                                                                                                                   |
| End Date      | string          | No       | Last UTC day to include (YYYY-MM-DD). This day is included. Needed for 'custom'.                                                                                                                              |
| Bucket Size   | select (string) | No       | Size of each time bucket. Narrower buckets cover a shorter maximum window: 31 days of daily buckets, 7 days of hourly, or 24 hours of minute buckets. Options load from the selected connection. Default: 1d. |
| Group By      | select (string) | No       | Break usage down by model, project, user, API key, batch flag or service tier. Options load from the selected connection.                                                                                     |
| Projects      | select (string) | No       | Limit the report to specific projects. Leave empty for all. Options load from the selected connection.                                                                                                        |
| Users         | select (string) | No       | Limit the report to usage from specific organization members. Not available on surfaces that report per project only. Options load from the selected connection.                                              |
| Models        | string          | No       | Limit the report to specific models. Comma-separated.                                                                                                                                                         |
| Maximum Pages | integer         | No       | How many result pages to fetch before stopping.                                                                                                                                                               |
| Start Cursor  | string          | No       | Resume a report that was cut short: pass the Next Cursor from the previous run.                                                                                                                               |

**Outputs**

| Field                | Type    | Description                                                                                                     |
| -------------------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| Usage Type           | string  | Which usage surface these figures describe.                                                                     |
| Primary Metric       | string  | Which figure actually matters for the selected surface.                                                         |
| Primary Metric Total | number  | The primary metric summed across the whole range.                                                               |
| Totals               | object  | Every metric summed across the buckets returned. Check Covers Full Range before reading it as the whole period. |
| Buckets              | array   | One entry per time bucket, with its usage lines.                                                                |
| Cached Input Share   | number  | Share of input tokens served from cache, as a percentage. Higher is cheaper.                                    |
| Start Date           | string  | Inclusive start of the range covered (ISO 8601 UTC).                                                            |
| End Date             | string  | Exclusive end of the range covered (ISO 8601 UTC).                                                              |
| Next Cursor          | string  | Pass this back as Start Cursor to continue where this stopped.                                                  |
| Truncated            | boolean | True when more pages were available than were fetched.                                                          |
| Covers Full Range    | boolean | True when the numbers below cover the whole date range that was asked for.                                      |

#### List Projects

List the projects in your OpenAI organization, with their names and IDs.

**Inputs**

| Field         | Type    | Required | Description                                                                         |
| ------------- | ------- | -------- | ----------------------------------------------------------------------------------- |
| Maximum Pages | integer | No       | How many result pages to fetch before stopping.                                     |
| After         | string  | No       | Continue a listing that was cut short. Paste the Next Cursor from the previous run. |

**Outputs**

| Field       | Type    | Description                                                     |
| ----------- | ------- | --------------------------------------------------------------- |
| Projects    | array   | Projects in the organization.                                   |
| Total Count | number  | Number of entries returned.                                     |
| Truncated   | boolean | True when the organization has more entries than were returned. |
| Next Cursor | string  | Cursor that continues a truncated listing.                      |

#### List Organization Members

List the members of your OpenAI organization, with their roles.

**Inputs**

| Field         | Type    | Required | Description                                                                         |
| ------------- | ------- | -------- | ----------------------------------------------------------------------------------- |
| Maximum Pages | integer | No       | How many result pages to fetch before stopping.                                     |
| After         | string  | No       | Continue a listing that was cut short. Paste the Next Cursor from the previous run. |

**Outputs**

| Field       | Type    | Description                                                     |
| ----------- | ------- | --------------------------------------------------------------- |
| Users       | array   | Members of the organization.                                    |
| Total Count | number  | Number of entries returned.                                     |
| Truncated   | boolean | True when the organization has more entries than were returned. |
| Next Cursor | string  | Cursor that continues a truncated listing.                      |

### Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/openai.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
