Working with Pivot Filters – Aspose.Cells Cloud Documentation

This REST API adds a pivot filter to the pivot table at the specified index.

Prerequisites
Before calling this endpoint you must:

  • Generate a valid OAuth/JWT access token and include it in the Authorization header.
  • Ensure the target workbook is stored in a cloud folder that you have access to (specify folder and optionally storageName).
  • Use Aspose.Cells Cloud API version 3.0 or later.

PutWorksheetPivotTableFilter API

PUT https://api.aspose.cloud/v3.0/cells/{name}/worksheets/{sheetName}/pivottables/{pivotTableIndex}/PivotFilters

Security and Authentication

The Aspose.Cells Cloud APIs are secure and require JWT token-based authentication.

Request parameters

Parameter Name Type Location Description
name string path The name of the Excel file.
sheetName string path The worksheet that contains the pivot table.
pivotTableIndex integer path Zero‑based index of the pivot table to which the filter will be applied.
filter object body JSON object that defines the filter settings. See the filter schema table below.
needReCalculate boolean query When true, forces the workbook to recalculate after the filter is added. Default false.
folder string query Folder in cloud storage where the file is located.
storageName string query Name of the cloud storage.

filter schema

Property Type Description
AutoFilter object Settings for an AutoFilter; can be omitted if not used.
EvaluationOrder integer Order in which the filter is evaluated.
FieldIndex integer Zero‑based index of the field to which the filter applies.
FilterType string Type of filter (e.g., Value, Count, Label).
MeasureFldIndex integer Index of the measure field, if applicable.
MemberPropertyFieldIndex integer Index of the member property field, if applicable.
Name string Optional name for the filter.
Value1 string First value used by the filter (e.g., lower bound for a range).
Value2 string Second value used by the filter (e.g., upper bound for a range).
CustomFilters array Collection of custom filter objects (each with FilterOperatorType, Value1, Value2).
DynamicFilter object Settings for a dynamic filter (e.g., Top10, Bottom10).
IconFilter object Settings for an icon‑based filter.
Top10Filter object Settings for a Top10/Bottom10 filter.
ColorFilter object Settings for a color‑based filter.
Visibledropdown boolean Indicates whether the filter dropdown is visible.

Note: All parameters listed above are required unless explicitly marked as optional in the API reference.

Response codes

Code Meaning
200 Filter added successfully.
400 Bad request – invalid parameters.
401 Unauthorized – missing or invalid token.
404 Not found – workbook or pivot table missing.
500 Internal server error.

Best Practices

  • Keep filter objects as small as possible; large filter definitions may increase request latency.
  • Calls are idempotent — adding the same filter twice will not create duplicates.
  • Respect the API rate‑limit of 100 requests per minute per account.

Additional notes:

  • The maximum size of a filter definition is 1 MB; larger payloads will be rejected with a 400 error.
  • When using needReCalculate=true, the recalculation may increase response time for large workbooks.

You can explore the full OpenAPI definition here:
OpenAPI Specification

Example cURL request

Cloud SDK Family

Using an SDK is the fastest way to develop against Aspose.Cells Cloud. SDKs handle low‑level details, letting you focus on your business logic. See the GitHub repository for a complete list of Aspose.Cells Cloud SDKs.

The following code examples demonstrate how to make calls to Aspose.Cells web services using various SDKs.

For additional operations related to pivot tables, see the Add, Delete, and Clear filter documentation.

Delete All Pivot Tables in an Excel Worksheet Convert table to pivot table