> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zapier.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get action details and needs

> Get details of a specific action, including its needs, gives, and a sample of the action.

"Needs" are the values that need to be provided when the action is run. Needs that are not provided will be guessed by the AI when the action is run.

"Gives" are the values that the action returns when it is run.

"Sample" is a sample of what the action returns when it is run.

When you [Run a stateless action](/ai-actions/how-tos/stateless/run-stateless-action), "needs" are provided to the endpoint. For each need, you can either have AI guess a value for it or you can ask the user to provide a specific value.

## Custom fields

<Warning>
  The list of needs that this returns can change based on the `params` provided in the request body.

  As such, this endpoint may need to be hit multiple times as needs are chosen by the user.
</Warning>

This endpoint needs to be hit again whenever the selected value for a need changes and *any of the following* are true:

* The changed need has `alters_custom_fields` set to `true`
* The changed need is in the `depends_on` array of another need
* The changed need has `custom_field` set to `true`

As an example, when using the `GoogleSheetsV2API` API with the `add_row` action, the first time you get the action you will get back these `action_needs`:

```json theme={null}
{
  "action_needs": [
    {
      "key": "spreadsheet",
      "label": "Spreadsheet",
      "prefill": "spreadsheet.id.title",
      "custom_field": false,
      "depends_on": [],
      "alters_custom_fields": true
    },
    {
      "key": "worksheet",
      "label": "Worksheet",
      "prefill": "worksheet.id.title",
      "custom_field": false,
      "depends_on": ["spreadsheet"],
      "alters_custom_fields": true
    }
  ]
}
```

In order to get the column names of the spreadsheet, you'll have to get the prefill choices. See [Get Prefill Choices](/ai-actions/how-tos/action-info/prefill-choices) for more information.

In this example scenario, after getting values for the `spreadsheet` and `worksheet` prefills, another call can be made to this endpoint.

This time, in the body of the `POST`, we can include the selected values:

```json theme={null}
{
  "params": {
    "spreadsheet": "SOME_SPREADSHEET_ID", // this is the ID of a spreadsheet in Google Sheets
    "worksheet": "0" // the first worksheet in the spreadsheet
  }
}
```

Now, the action details will include the columns from the spreadsheet as custom fields:

```json theme={null}
{
  "action_details": [
    // ... same results as above, in addition to...
    {
      "key": "COL$A",
      "label": "My first column",
      "prefill": null,
      "custom_field": true,
      "depends_on": [],
      "alters_custom_fields": null
    },
    {
      "key": "COL$B",
      "label": "My second column",
      "prefill": null,
      "custom_field": true,
      "depends_on": [],
      "alters_custom_fields": null
    },
    {
      "key": "COL$C",
      "label": "My third column",
      "prefill": null,
      "custom_field": true,
      "depends_on": [],
      "alters_custom_fields": null
    }
  ]
}
```

## Choices

If the need has a `choices` array, then the value being chosen should come from that list.

Often, you will see this with `boolean` fields.

For example, the `SlackAPI` API's `direct_message` action contains the following need (irrelevant fields removed):

```json theme={null}
{
  "key": "as_bot",
  "type": "boolean",
  "label": "Send as a bot?",
  "choices": [
    {
      "key": "no",
      "label": "No"
    },
    {
      "key": "yes",
      "label": "Yes"
    }
  ],
  "default": "yes",
  "format": "SELECT"
}
```

## Other field types

See [Field definitions and types](/integrations/build/field-definitions) in the Zapier Platform documentation for details on the other types of fields that a need can have.


## OpenAPI

````yaml post /api/v2/apps/{app}/actions/{action}/
openapi: 3.1.0
info:
  title: Zapier AI Actions API V2
  version: 1.0.0
  description: ''
servers:
  - url: https://actions.zapier.com
security: []
paths:
  /api/v2/apps/{app}/actions/{action}/:
    post:
      tags:
        - actions
      summary: Get Action Details
      description: >-
        Get details of a specific action, including its needs, gives, and a
        sample of the action.
      operationId: api_actions_get_action_details
      parameters:
        - in: path
          name: app
          schema:
            description: The app that the action belongs to.
            title: App
            type: string
          required: true
          description: The app that the action belongs to.
        - in: path
          name: action
          schema:
            description: The action to get details for.
            title: Action
            type: string
          required: true
          description: The action to get details for.
        - in: query
          name: action_type
          schema:
            allOf:
              - enum:
                  - read
                  - write
                  - search
                  - read_bulk
                title: ActionType
                type: string
            default: write
            description: >
              The type of the action to get details for.
                                           
              This can be:

              - `write`: Actions that have side effects (such as sending an
              email or updating a spreadsheet)

              - `search`: Actions that return results (such as searching for a
              contact or getting a list of emails)
          required: false
          description: >
            The type of the action to get details for.
                                         
            This can be:

            - `write`: Actions that have side effects (such as sending an email
            or updating a spreadsheet)

            - `search`: Actions that return results (such as searching for a
            contact or getting a list of emails)
        - in: query
          name: account_id
          schema:
            description: >

              The Zapier account ID to use.


              Account IDs available to the user can be listed using the [Get
              Account List](/docs/api-reference/meta/get-account-list) endpoint 
            title: Account Id
            type: integer
          required: false
          description: >

            The Zapier account ID to use.


            Account IDs available to the user can be listed using the [Get
            Account List](/docs/api-reference/meta/get-account-list) endpoint 
        - in: query
          name: authentication_id
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            description: >

              ID of the authentication to use for the app.


              Authentications available to the user can be listed using the
              [List Authentications For
              App](/docs/api-reference/actions/list-authentications-for-app)
              endpoint.
            title: Authentication Id
          required: false
          description: >

            ID of the authentication to use for the app.


            Authentications available to the user can be listed using the [List
            Authentications For
            App](/docs/api-reference/actions/list-authentications-for-app)
            endpoint.
        - in: query
          name: action_extra
          schema:
            default:
              - action_needs
            description: >

              What kind of information to return with the action details.
                                                   
              List of:

              - `action_needs`: Include the needs of the action. These are what
              are provided when running the action.   

              - `action_gives`: Include the gives of the action. These are what
              the action returns when it runs.

              - `action_sample`: Include a sample of the action. **Note:** This
              will dramatically slow down the response from this endpoint. Only
              use it if you really need the sample.
            items:
              enum:
                - action_needs
                - action_gives
                - action_sample
              title: ActionExtra
              type: string
            title: Action Extra
            type: array
            uniqueItems: true
          required: false
          description: >

            What kind of information to return with the action details.
                                                 
            List of:

            - `action_needs`: Include the needs of the action. These are what
            are provided when running the action.   

            - `action_gives`: Include the gives of the action. These are what
            the action returns when it runs.

            - `action_sample`: Include a sample of the action. **Note:** This
            will dramatically slow down the response from this endpoint. Only
            use it if you really need the sample.
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/ActionDetailsBodySchema'
              default:
                params: {}
        required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericResults_ActionDetailsResultSchema_'
      security:
        - AccessPointApiKeyHeader: []
        - AccessPointOAuth: []
components:
  schemas:
    ActionDetailsBodySchema:
      additionalProperties: true
      properties:
        params:
          description: >-
            A dictionary of key-value pairs, where the key is a `need` key and
            the value is a selected value for that need.
          title: Params
          type: object
      required:
        - params
      title: ActionDetailsBodySchema
      type: object
    GenericResults_ActionDetailsResultSchema_:
      additionalProperties: true
      properties:
        results:
          items:
            $ref: '#/components/schemas/ActionDetailsResultSchema'
          title: Results
          type: array
      required:
        - results
      title: GenericResults[ActionDetailsResultSchema]
      type: object
    ActionDetailsResultSchema:
      properties:
        action_has_custom_needs_probability:
          description: >-
            Probability this action has custom needs that vary from user to user
            (0.0 to 1.0). A score greater than 0.5 suggests it does.
          title: Action Has Custom Needs Probability
          type: number
        action:
          $ref: '#/components/schemas/ActionT'
        action_gives:
          items:
            $ref: '#/components/schemas/GivesT'
          title: Action Gives
          type: array
        action_needs:
          items:
            $ref: '#/components/schemas/NeedT'
          title: Action Needs
          type: array
        action_sample:
          title: Action Sample
          type: object
      required:
        - action_has_custom_needs_probability
        - action
        - action_gives
        - action_needs
        - action_sample
      title: ActionDetailsResultSchema
      type: object
    ActionT:
      properties:
        type:
          title: Type
          type: string
        key:
          title: Key
          type: string
        name:
          title: Name
          type: string
        noun:
          title: Noun
          type: string
        description:
          title: Description
          type: string
        is_important:
          title: Is Important
          type: boolean
        is_hidden:
          title: Is Hidden
          type: boolean
        needs:
          items:
            $ref: '#/components/schemas/NeedT'
          title: Needs
          type: array
        meta:
          anyOf:
            - $ref: '#/components/schemas/ActionMetaT'
            - type: 'null'
        popularity:
          anyOf:
            - type: integer
            - type: 'null'
          title: Popularity
        app_name:
          anyOf:
            - type: string
            - type: 'null'
          title: App Name
      required:
        - type
        - key
        - name
        - noun
        - description
        - is_important
        - is_hidden
      title: ActionT
      type: object
    GivesT:
      properties:
        key:
          title: Key
          type: string
        score:
          title: Score
          type: number
        subscore:
          title: Subscore
          type: number
        label:
          anyOf:
            - type: string
            - type: 'null'
          title: Label
        type:
          title: Type
          type: string
        zap_meta_sample:
          anyOf:
            - {}
            - type: 'null'
          title: Zap Meta Sample
        custom_field:
          default: false
          title: Custom Field
          type: boolean
        important:
          default: false
          title: Important
          type: boolean
      required:
        - key
        - score
        - subscore
        - type
      title: GivesT
      type: object
    NeedT:
      properties:
        key:
          title: Key
          type: string
        type:
          enum:
            - int
            - integer
            - float
            - decimal
            - unicode
            - text
            - str
            - string
            - datetime
            - boolean
            - bool
            - file
            - copy
            - password
            - dict
            - code
            - filter
            - confirmation
          title: Type
          type: string
        label:
          title: Label
          type: string
        required:
          title: Required
          type: boolean
        prefill:
          anyOf:
            - type: string
            - type: 'null'
          title: Prefill
        searchfill:
          anyOf:
            - type: string
            - type: 'null'
          title: Searchfill
        capabilities:
          items:
            type: string
          title: Capabilities
          type: array
        custom_field:
          title: Custom Field
          type: boolean
        depends_on:
          items:
            type: string
          title: Depends On
          type: array
        from_search:
          title: From Search
          type: boolean
        from_write:
          title: From Write
          type: boolean
        input_format:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          title: Input Format
        language:
          anyOf:
            - type: string
            - type: 'null'
          title: Language
        parent_key:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Key
        send_in_json:
          title: Send In Json
          type: boolean
        regex:
          anyOf:
            - type: string
            - type: 'null'
          title: Regex
        alters_custom_fields:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Alters Custom Fields
        choices:
          anyOf:
            - items:
                $ref: '#/components/schemas/ChoiceT'
              type: array
            - type: string
            - items:
                type: string
              type: array
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Choices
        default:
          anyOf:
            - type: string
            - type: integer
            - type: 'null'
          title: Default
        help_text:
          anyOf:
            - type: string
            - type: 'null'
          title: Help Text
        placeholder:
          anyOf:
            - type: string
            - type: 'null'
          title: Placeholder
        default_guessable:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Default Guessable
        list:
          title: List
          type: boolean
        format:
          anyOf:
            - type: string
            - type: 'null'
          title: Format
      title: NeedT
      type: object
    ActionMetaT:
      properties:
        hook:
          anyOf:
            - $ref: '#/components/schemas/ActionMetaHookT'
            - type: 'null'
      title: ActionMetaT
      type: object
    ChoiceT:
      properties:
        key:
          title: Key
          type: string
        label:
          title: Label
          type: string
        sample:
          title: Sample
          type: string
      title: ChoiceT
      type: object
    ActionMetaHookT:
      description: |-
        If this exists, then it means that this action is a webhook.

        Using the provided URL, you can send a POST request to it.
      properties:
        directions:
          anyOf:
            - type: string
            - type: 'null'
          title: Directions
        is_notification:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Notification
        is_pollable:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Pollable
        is_polling_notification:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Polling Notification
        is_subscription:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Subscription
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
      title: ActionMetaHookT
      type: object
  securitySchemes:
    AccessPointApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
    AccessPointOAuth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize/
          tokenUrl: /oauth/token/
          scopes:
            nla:exposed_actions:execute: Run AI Actions
            openid: OpenID Connect scope

````