# Fields, Filters, and Limit Many Enterprise API endpoints accept `filters`, `fields`, and `limit` input parameters to customize the data returned in the API response. When using these options, it is best to send requests using the POST method and include the parameters in the JSON request body. This page explains the correct placement, syntax, and available options, with examples of how to pass `fields`, `filters`, and `limit` in your requests. The following snippet is an example of a typical JSON request body. ```json { "filters": [ { "field": "is_part_of.identifier", "value": "enwiki" } ], "fields": ["name","url","is_part_of"], "limit": 1 } ``` ## Fields Use `fields` if you only want a specific set of fields and values returned in the API response, such as article names or category URLs. Omitting the `fields` parameter will return all available fields in the API response. The `fields` parameter takes an array of field names as input. Specify fields using dot notation. Any field in the API Response can be specified with `fields`: Objects such as `version`, arrays such as `version.tags`, or fields with a single value such as `version.is_minor_edit`. The [article model](https://enterprise.wikimedia.com/docs/api/#models/article) in the API reference lists all the fields present in Enterprise API responses. Example POST request using cURL to call the available Snapshots and only return the identifier info, date modified, and size of the snapshot: ```bash curl --location 'https://api.enterprise.wikimedia.com/v2/snapshots' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ACCESS_TOKEN' \ --data '{ "fields": ["is_part_of.identifier", "date_modified", "size.value"] }' ``` > **Important:** By passing the `fields` parameter, you are specifying which fields to **include exclusively.** Only the field names you pass in the `fields` parameter will be returned by the API; fields not explicitly mentioned will not be returned in the API response. ## Filters Use `filters` when you need to retrieve data from a specific range of values, such as data from a specific project, language, or namespace. Omitting the `filters` parameter will return all possible articles that match the API request. The `filters` parameter takes an array of objects as input. Every field specified in filters can only have one value associated with it. Only fields with a single value can be used in filters, e.g. `"field":"version.is_minor_edit", "value":true`. You cannot specify arrays (e.g. "`version.tags`"), or objects (e.g. "`version`"). Required fields can always be specified. Fields that are strings, integers, floats, and booleans can be used with filters. The [article model](https://enterprise.wikimedia.com/docs/api/#models/article) in the API reference lists all the fields present in Enterprise API responses. Example POST request using cURL to request all article data for "Marie Curie" in French: ```bash curl --location 'https://api.enterprise.wikimedia.com/v2/articles/Marie_Curie' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ACCESS_TOKEN' \ --data '{ "filters": [ { "field":"in_language.identifier", "value": "fr" } ] }' ``` > **Important:** By passing the `filters` parameter, you are **filtering in**, or **filtering down**, to a specific subset of Wikimedia data. If you specify `"field":"is_part_of.identifier", "value":"enwiki"` as a filter, the API will only return data from English Wikipedia, and not from any other Wikimedia projects or languages. ## Query form for GET requests Every endpoint that takes `fields` and `filters` in a POST body also takes them as query parameters on a GET request, with the same meaning. Send one `fields` parameter per field, and one `filters` parameter per filter with the filter object as JSON, URL-encoded. Repeated `filters` parameters combine as AND. A comma-separated list in a single `fields` value is not supported, and a JSON array in a single `filters` value returns `422 Unprocessable Entity`. The request for Marie Curie in French above, sent as GET and asking for two fields: ```bash curl -G 'https://api.enterprise.wikimedia.com/v2/articles/Marie_Curie' \ --header 'Authorization: Bearer ACCESS_TOKEN' \ --data-urlencode 'filters={"field":"in_language.identifier","value":"fr"}' \ --data-urlencode 'fields=name' \ --data-urlencode 'fields=version.identifier' ``` ## Limit Set a limit to restrict the number of articles returned in an API response. The default value for limit is 3, and its maximum value is 10. Limit can only be used with [On-demand endpoints](https://enterprise.wikimedia.com/docs/on-demand/). Example of an On-demand API POST call that limits the number of articles returned for the Wikipedia article NATO (which has almost 200 different languages) to 1: ```bash curl --location 'https://api.enterprise.wikimedia.com/v2/articles/NATO' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ACCESS_TOKEN' \ --data '{ "limit": 1 }' ``` ## See also - [On-demand API](https://enterprise.wikimedia.com/docs/on-demand/) - the only endpoints that accept `limit`. - [Snapshot API](https://enterprise.wikimedia.com/docs/snapshot/) - narrowing Snapshots Available and Snapshot Info. - [Metadata](https://enterprise.wikimedia.com/docs/metadata/) - the project, language, and namespace values you filter on. - [Article model](https://enterprise.wikimedia.com/docs/api/#models/article) - every field you can name in `fields` or `filters`.