> ## 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. # Execute a StoredAction > Execute Stored Action Executes an action on behalf of a user, this is an async process. Requires the id from a stored action Responds with the unique id for this run of the stored action. In order to fetch results you will need to poll the GET /stored-actions/{stored_action_id}/runs/{run_id} endpoint with that run id. **Billing** The Actions API offers support for directly billing users for Stored Action Runs, and this functionality is currently _opt-in_. To do this, you must provide a `billing` claim on the JWT used to authenticate. This claim must be a JSON string, and any values provided will override the default configuration shown below. The simplest approach is therefore to set `is_billable` to true, and successful Stored Action Runs will be charged to a user at a rate of one task. ```json billing: { "is_billable": false, "origin": "actions_api", "usage_type": "action_run", "description": "an action was run via Actions API", "exemption_reason": null, "exemption_details": null } ``` **Rate Limits** Rate limiting is applied when Gargoyle flag `edge_actions_api_rate_limiting_global` is active. Requests are rate limited by default unless the JWT explicitly sets `rate_limit.exempt` to true. ```json rate_limit: { "exempt": true } ``` Non-exempted requests are limited to 200 per 5 minutes by default. To set a custom limit, include `limit_override` (1–1000 requests per 5 minutes): ```json rate_limit: { "exempt": false, "limit_override": 500 } ``` ## OpenAPI ````yaml white-label/actions-openapi.yaml post /actions/v1/stored-actions/{stored_action_id}/run openapi: 3.1.0 info: title: Actions API description: > API for creating, executing, and fetching results for an Action. A Stored Action is a single, repeatable configuration that can been called repeatedly to execute the same action. As an example, you could create a StoredAction that sends a message to a specific channel in Slack. Every time that action is executed, a message will be sent to the pre-configured channel in Slack. An External Action is an action registered by an external provider (e.g., Custom Actions, Code Actions, Agents) in the Action Registry. External actions can be created, updated, published, shared, and controlled through the registry endpoints. An Action Run is a one-off execution of an action — no record is persisted for reuse. Submit the action configuration and inputs in a single POST /runs call, then poll GET /runs/{run_id} for the result. **Authentication:** Service and User JWTs # Key Terminology - `stored_action`: A pre-configured action connected to a SelectedAPI and executable action that can be called repeatedly. - `external_action`: An action registered by an external provider in the Action Registry. - `action_run`: A one-off execution of an action that is not persisted as a stored action. version: v1 contact: url: https://docs.zapier.com servers: - url: https://api.zapier.com description: Production security: - OAuth: [] tags: - name: Stored Actions description: Operations related to a Stored Action paths: /actions/v1/stored-actions/{stored_action_id}/run: post: tags: - Stored Actions summary: Execute a StoredAction description: >- Execute Stored Action Executes an action on behalf of a user, this is an async process. Requires the id from a stored action Responds with the unique id for this run of the stored action. In order to fetch results you will need to poll the GET /stored-actions/{stored_action_id}/runs/{run_id} endpoint with that run id. **Billing** The Actions API offers support for directly billing users for Stored Action Runs, and this functionality is currently _opt-in_. To do this, you must provide a `billing` claim on the JWT used to authenticate. This claim must be a JSON string, and any values provided will override the default configuration shown below. The simplest approach is therefore to set `is_billable` to true, and successful Stored Action Runs will be charged to a user at a rate of one task. ```json billing: { "is_billable": false, "origin": "actions_api", "usage_type": "action_run", "description": "an action was run via Actions API", "exemption_reason": null, "exemption_details": null } ``` **Rate Limits** Rate limiting is applied when Gargoyle flag `edge_actions_api_rate_limiting_global` is active. Requests are rate limited by default unless the JWT explicitly sets `rate_limit.exempt` to true. ```json rate_limit: { "exempt": true } ``` Non-exempted requests are limited to 200 per 5 minutes by default. To set a custom limit, include `limit_override` (1–1000 requests per 5 minutes): ```json rate_limit: { "exempt": false, "limit_override": 500 } ``` operationId: createStoredActionRun parameters: - in: path name: stored_action_id schema: type: string format: uuid required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/StoredActionsRunRequest' examples: ExamplePOSTRequest: value: data: inputs: message: Hello World! page: '0' summary: Example POST Request required: true responses: '202': content: application/json: schema: $ref: '#/components/schemas/StoredActionsRunResponse' examples: Accepted: value: data: type: run id: 123e4567-e89b-12d3-a456-426614174000 description: Acknowledges the request to execute a StoredAction headers: X-RateLimit-Limit: schema: type: integer description: >- Effective request cap per 300-second window. Default: 200. Maximum via limit_override: 1000. X-RateLimit-Remaining: schema: type: integer description: Requests remaining in the current window. X-RateLimit-Reset: schema: type: string format: date-time description: Unix timestamp when the current 300-second window resets. '400': content: application/json: schema: $ref: '#/components/schemas/ActionsErrorResponse' examples: BadRequest: value: errors: - status: 400 code: bad_request title: Bad Request detail: Improperly formatted or incompleted request source: null meta: {} summary: Bad Request description: Indicates an error executing the request to run a StoredAction. headers: X-RateLimit-Limit: schema: type: integer description: >- Effective request cap per 300-second window. Default: 200. Maximum via limit_override: 1000. X-RateLimit-Remaining: schema: type: integer description: Requests remaining in the current window. X-RateLimit-Reset: schema: type: string format: date-time description: Unix timestamp when the current 300-second window resets. '402': content: application/json: schema: $ref: '#/components/schemas/ActionsErrorResponse' examples: PaymentRequired: value: errors: - status: 402 code: payment_required title: Payment Required detail: Insufficient tasks on account summary: Payment Required description: Payment Required - insufficient tasks on account headers: X-RateLimit-Limit: schema: type: integer description: >- Effective request cap per 300-second window. Default: 200. Maximum via limit_override: 1000. X-RateLimit-Remaining: schema: type: integer description: Requests remaining in the current window. X-RateLimit-Reset: schema: type: string format: date-time description: Unix timestamp when the current 300-second window resets. '403': content: application/json: schema: $ref: '#/components/schemas/ActionsErrorResponse' examples: PermissionDenied: value: errors: - status: 403 code: permission_denied detail: >- User does not have enough permissions to perform action summary: Permission Denied description: Permission denied. Unauthorized request. '429': content: application/json: schema: $ref: '#/components/schemas/ActionsErrorResponse' examples: TooManyRequests: value: errors: - status: 429 code: too_many_requests detail: Rate limit exceeded. Too many requests. summary: Too Many Requests description: Too many requests. headers: X-RateLimit-Limit: schema: type: integer description: >- Effective request cap per 300-second window. Default: 200. Maximum via limit_override: 1000. X-RateLimit-Remaining: schema: type: integer description: Requests remaining in the current window. X-RateLimit-Reset: schema: type: string format: date-time description: Unix timestamp when the current 300-second window resets. Retry-After: schema: type: integer description: Seconds to wait before retrying. required: true '500': content: application/json: schema: $ref: '#/components/schemas/ActionsErrorResponse' examples: UnhandledOrExternalServiceError: value: errors: - status: 500 code: external_service_error detail: An error occurred with an external service. summary: Unhandled or External Service Error description: Internal Server Error headers: X-RateLimit-Limit: schema: type: integer description: >- Effective request cap per 300-second window. Default: 200. Maximum via limit_override: 1000. X-RateLimit-Remaining: schema: type: integer description: Requests remaining in the current window. X-RateLimit-Reset: schema: type: string format: date-time description: Unix timestamp when the current 300-second window resets. '503': content: application/json: schema: $ref: '#/components/schemas/ActionsErrorResponse' examples: ServiceUnavailableError: value: errors: - status: 503 code: service_unavaiable detail: Service is temporarily unavailable summary: Service Unavailable Error description: Service Unavailable headers: X-RateLimit-Limit: schema: type: integer description: >- Effective request cap per 300-second window. Default: 200. Maximum via limit_override: 1000. X-RateLimit-Remaining: schema: type: integer description: Requests remaining in the current window. X-RateLimit-Reset: schema: type: string format: date-time description: Unix timestamp when the current 300-second window resets. Retry-After: schema: type: integer description: Seconds to wait before retrying. required: true security: - OAuth: - external components: schemas: StoredActionsRunRequest: type: object properties: data: $ref: '#/components/schemas/StoredActionsRunRequestInput' required: - data StoredActionsRunResponse: type: object properties: data: $ref: '#/components/schemas/StoredActionsRunResponseParams' required: - data ActionsErrorResponse: type: object properties: errors: type: array items: $ref: '#/components/schemas/ActionsError' description: An array of error objects. required: - errors StoredActionsRunRequestInput: type: object description: The shape of a request payload accepted when running a stored action. properties: callback_url: type: string format: uri description: >- An optional URL that Zapier will POST the results to when the action completes. The POST body will match the same format as the GET /stored-actions/{stored_action_id}/runs/{run_id} response. maxLength: 2048 idempotency_id: type: string format: uuid description: >- A client-provided UUID that identifies this specific request. If the same idempotency_id is used within 72 hours, the second request will be ignored and the original response returned. inputs: default: {} description: >- Object that matches the input the action would normally get. Has all the same keys/types as the `input` of the action. (Formerly known as "needs" in some documentation) Specifically includes more "dynamic" information to execute such as a specific message when triggering an action that sends a Slack DM, for example. page: type: string description: >- When using bulk read action types, this denotes the state of the paging utilities. Pass it back into the stored-actions endpoint. StoredActionsRunResponseParams: type: object description: The data returned after running a stored action properties: type: type: string default: run description: >- Specifies the resource type, as required by the JSON:API specification. id: type: string format: uuid description: >- The UUID id that identifies this run of the execution and can be used to retrieve the results by polling the GET /stored-actions/{stored_action_id}/runs/{run_id} endpoint. ActionsError: type: object description: Base Error definition properties: status: type: integer description: The HTTP status code applicable to this problem. code: type: string description: A unique identifier for this particular occurrence of the problem. title: type: string description: A short summary of the problem. detail: type: string description: >- A human-readable explanation specific to this occurrence of the problem. source: oneOf: - $ref: '#/components/schemas/ActionsErrorSource' - type: 'null' description: An object containing references to the primary source of the error. meta: type: - object - 'null' additionalProperties: {} description: Any additional metadata about the error. ActionsErrorSource: type: object description: Populates the `source` object inside our error responses. properties: pointer: type: string description: >- Pointer to the value in the request document that caused the error e.g. `/actions`. parameter: type: string description: A string indicating which URI query parameter caused the error. header: type: string description: >- A string indicating the name of a single request header which caused the error. securitySchemes: OAuth: type: oauth2 description: OAuth 2.0 authentication. flows: authorizationCode: authorizationUrl: https://zapier.com/oauth/authorize tokenUrl: https://zapier.com/oauth/token scopes: external: Scope that gives access to all Public APIs clientCredentials: tokenUrl: https://zapier.com/oauth/token scopes: external: Scope that gives access to all Public APIs ````