---
title: "Get ElectronicStructureDoc documents"
method: GET
path: "/materials/electronic_structure/dos/"
tags: ["Materials Electronic Structure"]
---

# Get ElectronicStructureDoc documents

`GET /materials/electronic_structure/dos/`

## Query parameters

- `projection_type` string, nullable — Projection type for the density of states data.
- `spin` union — Spin channel for density of states data. '1' corresponds to spin up.
  - '1' | '-1'
  - 1 | -1 — Enum type for Spin. Only up and down. Usage: Spin.up, Spin.down.
- `element` 'H' | 'D' | 'T' | 'He' | 'Li' | 'Be' | 'B' | 'C' | 'N' | 'O' | 'F' | 'Ne' | 'Na' | 'Mg' | 'Al' | 'Si' | 'P' | 'S' | 'Cl' | 'Ar' | 'K' | 'Ca' | 'Sc' | 'Ti' | 'V' | 'Cr' | 'Mn' | 'Fe' | 'Co' | 'Ni' | 'Cu' | 'Zn' | 'Ga' | 'Ge' | 'As' | 'Se' | 'Br' | 'Kr' | 'Rb' | 'Sr' | 'Y' | 'Zr' | 'Nb' | 'Mo' | 'Tc' | 'Ru' | 'Rh' | 'Pd' | 'Ag' | 'Cd' | 'In' | 'Sn' | 'Sb' | 'Te' | 'I' | 'Xe' | 'Cs' | 'Ba' | 'La' | 'Ce' | 'Pr' | 'Nd' | 'Pm' | 'Sm' | 'Eu' | 'Gd' | 'Tb' | 'Dy' | 'Ho' | 'Er' | 'Tm' | 'Yb' | 'Lu' | 'Hf' | 'Ta' | 'W' | 'Re' | 'Os' | 'Ir' | 'Pt' | 'Au' | 'Hg' | 'Tl' | 'Pb' | 'Bi' | 'Po' | 'At' | 'Rn' | 'Fr' | 'Ra' | 'Ac' | 'Th' | 'Pa' | 'U' | 'Np' | 'Pu' | 'Am' | 'Cm' | 'Bk' | 'Cf' | 'Es' | 'Fm' | 'Md' | 'No' | 'Lr' | 'Rf' | 'Db' | 'Sg' | 'Bh' | 'Hs' | 'Mt' | 'Ds' | 'Rg' | 'Cn' | 'Nh' | 'Fl' | 'Mc' | 'Lv' | 'Ts' | 'Og' — Enum representing an element in the periodic table.
- `orbital` 0 | 1 | 2 | 3 — Enum type for orbital type. Indices are the azimuthal quantum number l.
- `band_gap_max` number, nullable — Maximum value for the band gap energy in eV.
- `band_gap_min` number, nullable — Minimum value for the band gap energy in eV.
- `efermi_max` number, nullable — Maximum value for the fermi energy in eV.
- `efermi_min` number, nullable — Minimum value for the fermi energy in eV.
- `magnetic_ordering` 'FM' | 'AFM' | 'FiM' | 'NM' | 'Unknown' — Enumeration defining possible magnetic orderings.
- `deprecated` boolean, nullable — Whether the material is marked as deprecated
- `_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 ElectronicStructureDoc as a list of comma separated strings. Fields include: `band_gap` `cbm` `vbm` `efermi` `is_gap_direct` `is_metal` `magnetic_ordering` `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` `property_name` `bandstructure` `dos`
- `_all_fields` boolean — Include all fields.
- `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 ElectronicStructureDoc

- ResponseElectronicStructureDoc
  - `data` ElectronicStructureDoc[], nullable — List of returned data
    - `band_gap` number, required — Band gap energy in eV.
    - `cbm` number, nullable — Conduction band minimum data.
    - `vbm` number, nullable — Valence band maximum data.
    - `efermi` number, nullable — Fermi energy in eV.
    - `is_gap_direct` boolean, nullable — Whether the band gap is direct.
    - `is_metal` boolean, nullable — Whether the material is a metal.
    - `magnetic_ordering` string, nullable — Magnetic ordering of the calculation.
    - `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 — Dictionary 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.
    - `property_name` string
    - `bandstructure` BandstructureData
      - `setyawan_curtarolo` BandStructureSummaryData — Schematize high-level band structure data for the API.
        - `band_gap` number, required — Band gap energy in eV.
        - `cbm` TypedBandDict — Type def for data stored for cbms or vbms
          - `band_index` object, required
          - `kpoint_index` integer[], required
          - `kpoint` TypedKpointDict, required
            - `@module` string, required
            - `@class` string, required
            - `lattice` MSONableTypedLatticeDict, required
              - …
            - `fcoords` number[], required
            - `ccoords` number[], required
            - `label` string, required
          - `energy` number, required
          - `projections` object, required
        - `vbm` TypedBandDict — Type def for data stored for cbms or vbms
          - `band_index` object, required
          - `kpoint_index` integer[], required
          - `kpoint` TypedKpointDict, required
            - `@module` string, required
            - `@class` string, required
            - `lattice` MSONableTypedLatticeDict, required
              - …
            - `fcoords` number[], required
            - `ccoords` number[], required
            - `label` string, required
          - `energy` number, required
          - `projections` object, required
        - `efermi` number, nullable — Fermi energy in eV.
        - `is_gap_direct` boolean, nullable — Whether the band gap is direct.
        - `is_metal` boolean, nullable — Whether the material is a metal.
        - `magnetic_ordering` string, nullable — Magnetic ordering of the calculation.
        - `task_id` unknown
        - `nbands` number, required — Number of bands.
        - `direct_gap` number, required — Direct gap energy in eV.
      - `hinuma` BandStructureSummaryData — Schematize high-level band structure data for the API.
        - `band_gap` number, required — Band gap energy in eV.
        - `cbm` TypedBandDict — Type def for data stored for cbms or vbms
          - `band_index` object, required
          - `kpoint_index` integer[], required
          - `kpoint` TypedKpointDict, required
            - `@module` string, required
            - `@class` string, required
            - `lattice` MSONableTypedLatticeDict, required
              - …
            - `fcoords` number[], required
            - `ccoords` number[], required
            - `label` string, required
          - `energy` number, required
          - `projections` object, required
        - `vbm` TypedBandDict — Type def for data stored for cbms or vbms
          - `band_index` object, required
          - `kpoint_index` integer[], required
          - `kpoint` TypedKpointDict, required
            - `@module` string, required
            - `@class` string, required
            - `lattice` MSONableTypedLatticeDict, required
              - …
            - `fcoords` number[], required
            - `ccoords` number[], required
            - `label` string, required
          - `energy` number, required
          - `projections` object, required
        - `efermi` number, nullable — Fermi energy in eV.
        - `is_gap_direct` boolean, nullable — Whether the band gap is direct.
        - `is_metal` boolean, nullable — Whether the material is a metal.
        - `magnetic_ordering` string, nullable — Magnetic ordering of the calculation.
        - `task_id` unknown
        - `nbands` number, required — Number of bands.
        - `direct_gap` number, required — Direct gap energy in eV.
      - `latimer_munro` BandStructureSummaryData — Schematize high-level band structure data for the API.
        - `band_gap` number, required — Band gap energy in eV.
        - `cbm` TypedBandDict — Type def for data stored for cbms or vbms
          - `band_index` object, required
          - `kpoint_index` integer[], required
          - `kpoint` TypedKpointDict, required
            - `@module` string, required
            - `@class` string, required
            - `lattice` MSONableTypedLatticeDict, required
              - …
            - `fcoords` number[], required
            - `ccoords` number[], required
            - `label` string, required
          - `energy` number, required
          - `projections` object, required
        - `vbm` TypedBandDict — Type def for data stored for cbms or vbms
          - `band_index` object, required
          - `kpoint_index` integer[], required
          - `kpoint` TypedKpointDict, required
            - `@module` string, required
            - `@class` string, required
            - `lattice` MSONableTypedLatticeDict, required
              - …
            - `fcoords` number[], required
            - `ccoords` number[], required
            - `label` string, required
          - `energy` number, required
          - `projections` object, required
        - `efermi` number, nullable — Fermi energy in eV.
        - `is_gap_direct` boolean, nullable — Whether the band gap is direct.
        - `is_metal` boolean, nullable — Whether the material is a metal.
        - `magnetic_ordering` string, nullable — Magnetic ordering of the calculation.
        - `task_id` unknown
        - `nbands` number, required — Number of bands.
        - `direct_gap` number, required — Direct gap energy in eV.
    - `dos` DosData
      - `task_id` unknown
      - `total` object, nullable — Total DOS summary data.
      - `elemental` object, nullable — Band structure summary data using the Hinuma et al. path convention.
      - `orbital` object, nullable — Band structure summary data using the Latimer-Munro path convention.
      - `magnetic_ordering` string, nullable — Magnetic ordering of the calculation.
  - `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

## Changes

- **2026-08-20** `70f72d0670df` — 4 info
  - added the new optional `query` request parameter `id_format`
  - the `api_version` response's property default value changed from `0.87.2.dev19+g3f2daf4f8` to `0.87.3.dev3+gfbe8656b6` for the status `200`
  - the `emmet_version` response's property default value changed from `0.87.1` to `0.87.2` for the status `200`
  - the `pymatgen_version` response's property default value changed from `2026.5.18` to `2026.8.13` for the status `200`
- **2026-07-31** `54f2f79ab4f8` — 1 info
  - the `api_version` response's property default value changed from `0.87.2.dev13+g62063a867` to `0.87.2.dev19+g3f2daf4f8` for the status `200`
- **2026-07-26** `9aac4fdf4081` — 1 info
  - the `api_version` response's property default value changed from `0.87.2.dev4+g6bd8ed856` to `0.87.2.dev13+g62063a867` for the status `200`

[Change history](https://skmtc.dev/materialsproject/apis/materials-project-api/changes/materials/electronic_structure/dos/get.md)

---

[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)