---
title: "Get CoreTaskDoc documents"
method: GET
path: "/materials/tasks/"
tags: ["Materials Tasks"]
---

# Get CoreTaskDoc documents

`GET /materials/tasks/`

## Query parameters

- `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
- `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.
- `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
- `last_updated_min` string, date-time, nullable — Minimum last updated UTC datetime
- `last_updated_max` string, date-time, nullable — Maximum last updated UTC datetime
- `_forward` boolean — Whether to page forward (True) or backward (False) in the search results.
- `_pagination_token` string — Pagination token for the next set of results.
- `_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 CoreTaskDoc as a list of comma separated strings. Fields include: `nsites` `elements` `nelements` `composition` `composition_reduced` `formula_pretty` `formula_anonymous` `chemsys` `volume` `density` `density_atomic` `symmetry` `batch_id` `calc_type` `completed_at` `dir_name` `icsd_id` `input` `last_updated` `orig_inputs` `output` `run_type` `structure` `tags` `task_id` `task_type` `transformations` `vasp_objects` `vasp_version`
- `_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 CoreTaskDoc

- ResponseCoreTaskDoc
  - `data` CoreTaskDoc[], nullable — List of returned data
    - `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
    - `batch_id` string, nullable — Identifier for this calculation; should provide rough information about the calculation origin and purpose.
    - `calc_type` string, nullable — The functional and task type used in the calculation.
    - `completed_at` string, date-time, nullable — Timestamp for when this task was completed
    - `dir_name` string, nullable — The directory for this VASP task
    - `icsd_id` integer, nullable — Inorganic Crystal Structure Database id of the structure
    - `input` CalculationInput — Document defining VASP calculation inputs. Note that the following fields were formerly top-level fields on InputDoc, but are now properties of `CalculationInput`: pseudo_potentials (Potcar) : summary of the POTCARs used in the calculation xc_override (str) : the exchange-correlation functional used if not the one specified by POTCAR is_lasph (bool) : how the calculation set LASPH (aspherical corrections) magnetic_moments (list of floats) : on-site magnetic moments
      - `incar` object, nullable — INCAR parameters for the calculation
      - `kpoints` object, nullable — KPOINTS for the calculation
      - `nkpoints` integer, nullable — Total number of k-points
      - `potcar_spec` PotcarSpec[], nullable — Title and hash of POTCAR files used in the calculation
        - `titel` string, nullable — TITEL field from POTCAR header
        - `hash` string, nullable — md5 hash of POTCAR file
        - `summary_stats` TypedPotcarSummaryStatsDict
          - `keywords` TypedPotcarKeywordsDict
            - `header` string[], required
            - `data` string[], required
          - `stats` TypedPotcarStatsDict
            - `header` TypedStatisticsDict, required
              - …
            - `data` TypedStatisticsDict, required
              - …
      - `potcar` string[], nullable — The symbols of the POTCARs used in the calculation.
      - `potcar_type` string[], nullable — List of POTCAR functional types.
      - `parameters` object, nullable — Parameters from vasprun
      - `lattice_rec` MSONableTypedLatticeDict
        - `@module` string, required
        - `@class` string, required
        - `matrix` array[], required
          - number[]
        - `pbc` unknown[], required
          - unknown
        - `a` number, required
        - `b` number, required
        - `c` number, required
        - `alpha` number, required
        - `beta` number, required
        - `gamma` number, required
        - `volume` number, required
      - `structure` TypedStructureDict — unresolved $ref
      - `is_hubbard` boolean — Is this a Hubbard +U calculation
      - `hubbards` object, nullable — The hubbard parameters used
    - `last_updated` string, date-time — Timestamp for the most recent calculation for this task document
    - `orig_inputs` CalculationInput — Document defining VASP calculation inputs. Note that the following fields were formerly top-level fields on InputDoc, but are now properties of `CalculationInput`: pseudo_potentials (Potcar) : summary of the POTCARs used in the calculation xc_override (str) : the exchange-correlation functional used if not the one specified by POTCAR is_lasph (bool) : how the calculation set LASPH (aspherical corrections) magnetic_moments (list of floats) : on-site magnetic moments
      - `incar` object, nullable — INCAR parameters for the calculation
      - `kpoints` object, nullable — KPOINTS for the calculation
      - `nkpoints` integer, nullable — Total number of k-points
      - `potcar_spec` PotcarSpec[], nullable — Title and hash of POTCAR files used in the calculation
        - `titel` string, nullable — TITEL field from POTCAR header
        - `hash` string, nullable — md5 hash of POTCAR file
        - `summary_stats` TypedPotcarSummaryStatsDict
          - `keywords` TypedPotcarKeywordsDict
            - `header` string[], required
            - `data` string[], required
          - `stats` TypedPotcarStatsDict
            - `header` TypedStatisticsDict, required
              - …
            - `data` TypedStatisticsDict, required
              - …
      - `potcar` string[], nullable — The symbols of the POTCARs used in the calculation.
      - `potcar_type` string[], nullable — List of POTCAR functional types.
      - `parameters` object, nullable — Parameters from vasprun
      - `lattice_rec` MSONableTypedLatticeDict
        - `@module` string, required
        - `@class` string, required
        - `matrix` array[], required
          - number[]
        - `pbc` unknown[], required
          - unknown
        - `a` number, required
        - `b` number, required
        - `c` number, required
        - `alpha` number, required
        - `beta` number, required
        - `gamma` number, required
        - `volume` number, required
      - `structure` TypedStructureDict — unresolved $ref
      - `is_hubbard` boolean — Is this a Hubbard +U calculation
      - `hubbards` object, nullable — The hubbard parameters used
    - `output` CoreCalculationOutput — unresolved $ref
    - `run_type` string, nullable — The functional used in the calculation.
    - `structure` TypedStructureDict — unresolved $ref
    - `tags` string[], nullable — Metadata tagged to a given task.
    - `task_id` unknown
    - `task_type` string, nullable — The type of calculation.
    - `transformations` object, nullable — Information on the structural transformations, parsed from a transformations.json file
    - `vasp_objects` object, nullable — Vasp objects associated with this task
    - `vasp_version` string, nullable — The version of VASP used for this task.
  - `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` — 2 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`
- **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/tasks/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)