---
title: "Get MaterialsDoc documents"
method: GET
path: "/materials/core/"
tags: ["Materials"]
---

# Get MaterialsDoc documents

`GET /materials/core/`

## Query parameters

- `material_ids` string, nullable — Comma-separated list of material_id values to query on
- `formula` string, nullable — Query by formula including anonymized formula or by including wild cards. A comma delimited string list of anonymous formulas or regular formulas can also be provided.
- `chemsys` string, nullable — A comma delimited string list of chemical systems. Wildcards for unknown elements only supported for single chemsys queries
- `elements` string, nullable — Query by elements in the material composition as a comma-separated list
- `exclude_elements` string, nullable — Query by excluded elements in the material composition as a comma-separated list
- `task_ids` string, nullable — Comma-separated list of task_ids to query on
- `crystal_system` string, nullable — Crystal system of the material. If a comma-separated string, will query by multiple crystal systems.
- `spacegroup_number` union — Space group number of the material. If a comma-separated string, will query by multiple space group numbers.
  - integer
  - string
- `spacegroup_symbol` string, nullable — Space group symbol of the material. If a comma-separated string, will query by multiple space group numbers.
- `deprecated` boolean, nullable — Whether the material is marked as deprecated
- `nsites_max` integer, nullable — Query for maximum value of nsites
- `nsites_min` integer, nullable — Query for minimum value of nsites
- `nsites` integer, nullable — Query for nsites being equal to an exact value
- `nsites_not_eq` integer, nullable — Query for nsites being not equal to an exact value
- `nsites_eq_any` string — Query for nsites being any of these values. Provide a comma separated list.
- `nsites_neq_any` string — Query for nsites being not any of these values. Provide a comma separated list.
- `nelements_max` integer, nullable — Query for maximum value of nelements
- `nelements_min` integer, nullable — Query for minimum value of nelements
- `nelements` integer, nullable — Query for nelements being equal to an exact value
- `nelements_not_eq` integer, nullable — Query for nelements being not equal to an exact value
- `nelements_eq_any` string — Query for nelements being any of these values. Provide a comma separated list.
- `nelements_neq_any` string — Query for nelements being not any of these values. Provide a comma separated list.
- `volume_max` number, nullable — Query for maximum value of volume
- `volume_min` number, nullable — Query for minimum value of volume
- `density_max` number, nullable — Query for maximum value of density
- `density_min` number, nullable — Query for minimum value of density
- `density_atomic_max` number, nullable — Query for maximum value of density_atomic
- `density_atomic_min` number, nullable — Query for minimum value of density_atomic
- `_page` integer — Page number to request (takes precedent over _limit and _skip).
- `_per_page` integer — Number of entries to show per page (takes precedent over _limit and _skip). Limited to 1000.
- `_skip` integer — Number of entries to skip in the search.
- `_limit` integer — Max number of entries to return in a single query. Limited to 1000.
- `_fields` string — Fields to project from MaterialsDoc as a list of comma separated strings. Fields include: `builder_meta` `nsites` `elements` `nelements` `composition` `composition_reduced` `formula_pretty` `formula_anonymous` `chemsys` `volume` `density` `density_atomic` `symmetry` `material_id` `deprecated` `deprecation_reasons` `last_updated` `origins` `warnings` `structure` `initial_structures` `task_ids` `deprecated_tasks` `calc_types` `created_at` `task_types` `run_types` `entries`
- `_all_fields` boolean — Include all fields.
- `license` 'BY-C' | 'BY-NC' | 'All', nullable — Query by license. Can be commercial or non-commercial, or both
- `batch_id` string, nullable — Query by batch identifier
- `batch_id_not_eq` string, nullable — Exclude batch identifier
- `batch_id_eq_any` string, nullable — Query by a comma-separated list of batch identifiers
- `batch_id_neq_any` string, nullable — Exclude a comma-separated list of batch identifiers
- `id_format` string, nullable — Optional. If set to 'legacy', MP identifier fields in the response are returned in the form 'mp-149'. If set to 'alpha', they are returned in the padded AlphaID form 'mp-aaaaaaft'. If omitted (or set to any other value), identifiers are returned in their stored form. This is a purely cosmetic transform; query inputs accept either shape regardless.

## Response `200`

Search for a MaterialsDoc

- ResponseMaterialsDoc
  - `data` MaterialsDoc[], nullable — List of returned data
    - `builder_meta` EmmetMeta — Default emmet metadata.
      - `emmet_version` string, nullable — The version of emmet this document was built with.
      - `pymatgen_version` string, nullable — The version of pymatgen this document was built with.
      - `run_id` string, nullable — The run id associated with this data build.
      - `batch_id` string, nullable — Identifier corresponding to the origin of this document's blessed task.
      - `database_version` string, nullable — The database version for the built data.
      - `build_date` string, date-time, nullable — The build date for this document.
      - `license` 'BY-C' | 'BY-NC', nullable — License for the data entry.
    - `nsites` integer, nullable — Total number of sites in the structure.
    - `elements` string[], nullable — List of elements in the material.
    - `nelements` integer, nullable — Number of elements.
    - `composition` object, nullable — Full composition for the material.
    - `composition_reduced` object, nullable — Simplified representation of the composition.
    - `formula_pretty` string, nullable — Cleaned representation of the formula.
    - `formula_anonymous` string, nullable — Anonymized representation of the formula.
    - `chemsys` string, nullable — Dash-separated string of elements in the material.
    - `volume` number, nullable — Total volume for this structure in ų.
    - `density` number, nullable — Density in g/cm³.
    - `density_atomic` number, nullable — The atomic packing density in ų/atom.
    - `symmetry` SymmetryData — Defines a symmetry data set for materials documents
      - `crystal_system` string, nullable — The crystal system for this lattice.
      - `symbol` string, nullable — The spacegroup symbol for the lattice.
      - `hall` string, nullable — Hall symbol for the lattice
      - `number` integer, nullable — The spacegroup number for the lattice.
      - `point_group` string, nullable — The point group for the lattice.
      - `symprec` number, nullable — The precision provided to spglib to determine the symmetry of this structure.
      - `angle_tolerance` number, nullable — Angle tolerance provided to spglib to determine the symmetry of this structure.
      - `version` string, nullable
    - `material_id` unknown
    - `deprecated` boolean — Whether this property document is deprecated.
    - `deprecation_reasons` string[], nullable — List of deprecation tags detailing why this document isn't valid.
    - `last_updated` string, date-time — Timestamp for the most recent calculation update for this property.
    - `origins` PropertyOrigin[], nullable — Struct array for tracking the provenance of properties
      - `name` string, required — The property name
      - `task_id` unknown, required
      - `last_updated` string, date-time — The timestamp when this calculation was last updated
    - `warnings` string[] — Any warnings related to this property.
    - `structure` TypedStructureDict, required — unresolved $ref
    - `initial_structures` TypedStructureDict[] — Initial structures used in the DFT optimizations corresponding to this material. — unresolved $ref
    - `task_ids` unknown[] — List of Calculations IDs used to make this Materials Document.
      - unknown
    - `deprecated_tasks` string[]
    - `calc_types` object, nullable — Calculation types for all the calculations that make up this material
    - `created_at` string, date-time — Timestamp for when this material document was first created.
    - `task_types` object, nullable — Task types for all the calculations that make up this material
    - `run_types` object, nullable — Run types for all the calculations that make up this material
    - `entries` BlessedCalcs
      - `GGA` object, nullable
      - `GGA+U` object, nullable
      - `PBEsol` object, nullable
      - `SCAN` object, nullable
      - `r2SCAN` object, nullable
      - `HSE06` object, nullable
  - `errors` Error[], nullable — Any errors on processing this query
    - `code` integer, required — The error code
    - `message` string, required — The description of the error
  - `meta` Meta — Meta information for the MAPI Response.
    - `api_version` string — A string containing the version of the Materials API implementation, e.g. v0.9.5
    - `time_stamp` string, date-time — A string containing the date and time at which the query was executed
    - `total_doc` integer, nullable — The total number of documents available for this query
    - `facet` object, nullable — A dictionary containing the facets available for this query

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/materialsproject/apis/materials-project-api.md) · [All operations](https://skmtc.dev/materialsproject/apis/materials-project-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/materialsproject/materials-project-api/revisions/70f72d0670df/schema)