All around the Interwebs I see advice from people who say that when you want to get posts in a custom taxonomy you should use the filter parameter, for example:


This seems like a very handy parameter. But in v2 of the WP REST API it just doesn't work. When I created a WP Trac ticket to find out what was going on, @swissspidy responded that "the filter param has been removed on purpose" but that the documentation hasn't been updated yet. The change is discussed in Trac ticket 38378.

OK, fair enough, but could someone tell me how I should retrieve posts in a custom taxonomy now? I'm writing a plugin that depends on being able to do this.

For example, if I've created a non-hierarchical custom taxonomy instance and given it the value 1 for certain posts in a custom post type, how can I retrieve all the posts of that type and with instance=1?

If it's not possible via the REST API, is there a way to do it via the WordPress.com API on a Jetpack-enabled self-hosted site?

  • Try this plugin github.com/bueltge/wp-rest-api-filter-items
    – bueltge
    Dec 7, 2016 at 9:41
  • Thanks @bueltge, but it looks like that plugin is to filter what fields the API returns for each post? Dec 7, 2016 at 12:19
  • Currently it helps to filter posts, comments, taxonomies. If you need more, a enhancement in github.com/bueltge/wp-rest-api-filter-items/tree/master/inc/… is necessary.
    – bueltge
    Dec 7, 2016 at 13:12
  • 1
    Also in this context github.com/WP-API/rest-filter
    – bueltge
    Dec 7, 2016 at 18:14
  • Ah thank you! That's the kind of filter I was talking about! If you want to post that as an answer I'll accept it. Presumably there were good reasons for removing the filter argument, so it may not be the best thing in every case to restore it, but that's an extremely handy plugin which points me towards how to achieve what I want to do. Dec 8, 2016 at 11:41

2 Answers 2


Since WordPress 4.7 the filter argument for any post endpoint was removed. But if you need them, add them via plugin. The WP API Repo have a plugin 'Rest Filter' for this job, small and short.

  • 1
    Thanks! This did it for me. I wasn't sure if there were downsides to restoring the entire filter argument, so instead of installing the plugin I just followed its example to create a rest api query filter for my custom post type that adds $args['tax_query'] to the args. This enables me to filter my custom posts according to custom taxonomy tag in the API. But for people who want to restore the filter argument the plugin will do the trick. Dec 8, 2016 at 12:29
  • @AndFinally do you mind posting how you accomplished your taxonomy filter on the custom post types, would be a big help!
    – bmiskie
    Apr 10, 2017 at 17:33
  • @bmiskie Just install the plugin and the filter param should work like before
    – Sisir
    Jul 24, 2017 at 9:09
  • 1
    I looked at the github issue for the filter param (github.com/WP-API/WP-API/issues/2799) and it points to a slack channel which I'm not part of so I can't see the reasons behind the decision. Can anyone explain why it was removed?
    – jagershark
    Oct 2, 2018 at 16:14

The WordPress REST API documentation has a section on registering custom posts and taxonomies with the API. Essentially, you add 'show_in_rest' => true when registering the custom post type or custom taxonomy.

register_taxonomy('instance', ['post'], [
    <other args...>,
    'show_in_rest' => true,

Once that's done, you can filter any object for which you registered that taxonomy ('post' in the above example) by that custom taxonomy by using its name as a query string parameter, e.g.:


Note that the value of the taxonomy parameter ('1' in the above example) has to be the id of the taxonomy object, not it's name or slug. If you only know the slug, and not the id, you can first lookup the id by separately querying for it, because registering your custom taxonomy with the API also creates its own custom endpoint:


Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.