New Mat Project API, search for materials with specific number of elements, keyword 'nelements' not known?

Dear all,
I’m trying the new API with the python client mp-api in Version: 0.29.7 (via poetry/pip)

When I look at the available fields:

with MPRester(api_token) as m:
    fields = m.summary.available_fields

I get:
['builder_meta', 'nsites', 'elements', 'nelements', 'composition', ....]

However, when I try to use it:

with MPRester(api_token) as m:
    docs =,

I get:
TypeError                                 Traceback (most recent call last)
Cell In [5], line 3
      1 # get all materials with only one element
      2 with MPRester(api_token) as m:
----> 3     docs =,
      4                             fields=['material_id', 
      5                                     'formula_pretty',
      6                                     'elements']
      7         )

TypeError: got an unexpected keyword argument 'nelements'

It works if I do, e.g. the following (including nelements in the "fields")
with MPRester(api_token) as m:
    docs =['Al'],

Any suggestion what I might be doing wrong would be much appreciated.

many thanks

Hi @Ulrich, welcome!

This is a great question. If you look at the docstring for (or, if you tab-complete, or access inline help if you’re using Jupyter), you’ll see there’s a num_elements option which you can use. This takes a list, e.g. num_elements = [1, 4] will give materials with the number of elements between 1 and 4 (inclusive).

The inconsistency between the field name of the returned data, nelements, and the name in search num_elements is confusing, and probably something we should fix to be more consistent. Tagging @munrojm here too, since we’re having a discussion about naming conventions for the new API.



1 Like

Dear Matt,

ah, thank you for the hint.
Tbh, it didn’t occur to me tolook at the docstring…
I started from the API at Materials Project API - Swagger UI and thought that the following would do what I wanted:



(query) Query for nelements being equal to an exact value

I’ll give num_elements a go.

Many thanks for your help!

1 Like