Materials Project Materials Tasks API

openapi: 3.2.0
info:
  title: Materials Project Defect Tasks Materials Tasks API
  description: "\nThe Materials Project API allows anyone to have direct access to current, up-to-date information from the Materials Project database in a structured way.\n\nThis allows for analysis, development of automated tools, machine learning, downloading personal copies of the Materials Project database and more on a large scale.\n\nThe API is offered with the hopes of making Materials Project data more useful to you. We want you to use our data! As such, the API is offered free-of-charge and we support several tools to help you get started.\n\n## API Key\nTo make any request to the Materials Project API, you must use an API key. Your API key is generated for you automatically upon registering with the Materials Project website and is synced with the email you used to register.\n\nRemember to keep your API key safe and to not share it with anyone you do not trust.\n\nIf you are logged in, you can always access your API key from this page or from your [dashboard](https://next-gen.materialsproject.org/dashboard).\n\nIf you intend heavy API usage, you can give us a heads up by sending a message to <heavy.api.use@materialsproject.org>. With the exception of retrieving charge densities, this is not required, but may help us if we see unusual load on our servers.\n\n## Accessing Data\nTo use the API, you have three options:\n\n1. You can use our first-party supported Python client. This is the recommend route. The `mp-api` package containing the client is pip installable.\n\n    ```\n    pip install mp-api\n    ```\n\n    The `MPRester` client can be accessed by importing from it. This will ultimately replace the legacy `MPRester` available in pymatgen.\n\n    For more details on how to use this, including code examples, please see <https://next-gen.materialsproject.org/api>.\n\n2. You can demo the API interactively on this documentation page. Click the \"Authorize\" button, paste in your API key, and then click the appropriate section to try out a query.\n\n3. Since this is a REST API, and offers a fully-compliant OpenAPI specification, it's possible to use the API with many libraries in many languages and environments, including JavaScript, MATLAB, Mathematica, etc. However, we do not offer first-party support for explaining how to do this, and you will have to follow the specification yourself.\n\n"
  version: 0.86.4rc5.dev1+g77c2c1315
  x-logo:
    url: https://raw.githubusercontent.com/materialsproject/emmet/master/emmet-api/emmet/api/core/assets/mp_logo_small.png
servers:
- url: https://api.materialsproject.org
  description: Base URL declared by the provider in apis.yml (roadmap#122).
security:
- ApiKeyAuth: []
tags:
- name: Materials Tasks
  description: Route for "core" information associated with a given calculation in the Materials Project             database. Multiple calculations can ultimately be associated with a unique material, and are the source             of its reported properties. The unique identifier for a calculation is its `task_id`. Note             that the `material_id` chosen for a given material is sourced from one of the `task_id` values             associated with it. Core data in this context refers to calculation quantities such as parsed input             and output data (e.g. VASP input flags, atomic forces, structures) and runtime statistics. See the             `TaskDoc` schema for a full list of fields returned by this route.
paths:
  /materials/tasks/trajectory/:
    get:
      tags:
      - Materials Tasks
      summary: Get TrajectoryDoc documents
      operationId: search_materials_tasks_trajectory__get
      parameters:
      - name: task_ids
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Comma-separated list of task_ids to query on
          title: Task Ids
        description: Comma-separated list of task_ids to query on
      - name: _page
        in: query
        required: false
        schema:
          type: integer
          description: Page number to request (takes precedent over _limit and _skip).
          title: ' Page'
        description: Page number to request (takes precedent over _limit and _skip).
      - name: _per_page
        in: query
        required: false
        schema:
          type: integer
          description: Number of entries to show per page (takes precedent over _limit and _skip). Limited to 1000.
          default: 100
          title: ' Per Page'
        description: Number of entries to show per page (takes precedent over _limit and _skip). Limited to 1000.
      - name: _skip
        in: query
        required: false
        schema:
          type: integer
          description: Number of entries to skip in the search.
          default: 0
          title: ' Skip'
        description: Number of entries to skip in the search.
      - name: _limit
        in: query
        required: false
        schema:
          type: integer
          description: Max number of entries to return in a single query. Limited to 1000.
          default: 100
          title: ' Limit'
        description: Max number of entries to return in a single query. Limited to 1000.
      responses:
        '200':
          description: Search for a TrajectoryDoc
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response_TrajectoryDoc_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /materials/tasks/entries/:
    get:
      tags:
      - Materials Tasks
      summary: Get EntryDoc documents
      operationId: search_materials_tasks_entries__get
      parameters:
      - name: task_ids
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Comma-separated list of task_ids to query on
          title: Task Ids
        description: Comma-separated list of task_ids to query on
      - name: _page
        in: query
        required: false
        schema:
          type: integer
          description: Page number to request (takes precedent over _limit and _skip).
          title: ' Page'
        description: Page number to request (takes precedent over _limit and _skip).
      - name: _per_page
        in: query
        required: false
        schema:
          type: integer
          description: Number of entries to show per page (takes precedent over _limit and _skip). Limited to 1000.
          default: 100
          title: ' Per Page'
        description: Number of entries to show per page (takes precedent over _limit and _skip). Limited to 1000.
      - name: _skip
        in: query
        required: false
        schema:
          type: integer
          description: Number of entries to skip in the search.
          default: 0
          title: ' Skip'
        description: Number of entries to skip in the search.
      - name: _limit
        in: query
        required: false
        schema:
          type: integer
          description: Max number of entries to return in a single query. Limited to 1000.
          default: 100
          title: ' Limit'
        description: Max number of entries to return in a single query. Limited to 1000.
      responses:
        '200':
          description: Search for a EntryDoc
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response_EntryDoc_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /materials/tasks/deprecation/:
    get:
      tags:
      - Materials Tasks
      summary: Get DeprecationDoc documents
      operationId: search_materials_tasks_deprecation__get
      parameters:
      - name: task_ids
        in: query
        required: true
        schema:
          type: string
          description: Comma-separated list of task_ids to query on
          title: Task Ids
        description: Comma-separated list of task_ids to query on
      - name: _page
        in: query
        required: false
        schema:
          type: integer
          description: Page number to request (takes precedent over _limit and _skip).
          title: ' Page'
        description: Page number to request (takes precedent over _limit and _skip).
      - name: _per_page
        in: query
        required: false
        schema:
          type: integer
          description: Number of entries to show per page (takes precedent over _limit and _skip). Limited to 1000.
          default: 100
          title: ' Per Page'
        description: Number of entries to show per page (takes precedent over _limit and _skip). Limited to 1000.
      - name: _skip
        in: query
        required: false
        schema:
          type: integer
          description: Number of entries to skip in the search.
          default: 0
          title: ' Skip'
        description: Number of entries to skip in the search.
      - name: _limit
        in: query
        required: false
        schema:
          type: integer
          description: Max number of entries to return in a single query. Limited to 1000.
          default: 100
          title: ' Limit'
        description: Max number of entries to return in a single query. Limited to 1000.
      responses:
        '200':
          description: Search for a DeprecationDoc
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response_DeprecationDoc_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /materials/tasks/:
    get:
      tags:
      - Materials Tasks
      summary: Get TaskDoc documents
      operationId: search_materials_tasks__get
      parameters:
      - name: batch_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Query by batch identifier
          title: Batch Id
        description: Query by batch identifier
      - name: batch_id_not_eq
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Exclude batch identifier
          title: Batch Id Not Eq
        description: Exclude batch identifier
      - name: batch_id_eq_any
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Query by a comma-separated list of batch identifiers
          title: Batch Id Eq Any
        description: Query by a comma-separated list of batch identifiers
      - name: batch_id_neq_any
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Exclude a comma-separated list of batch identifiers
          title: Batch Id Neq Any
        description: Exclude a comma-separated list of batch identifiers
      - name: formula
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 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.
          title: Formula
        description: 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.
      - name: elements
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Query by elements in the material composition as a comma-separated list
          title: Elements
        description: Query by elements in the material composition as a comma-separated list
      - name: exclude_elements
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Query by excluded elements in the material composition as a comma-separated list
          title: Exclude Elements
        description: Query by excluded elements in the material composition as a comma-separated list
      - name: task_ids
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Comma-separated list of task_ids to query on
          title: Task Ids
        description: Comma-separated list of task_ids to query on
      - name: last_updated_min
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Minimum last updated UTC datetime
          title: Last Updated Min
        description: Minimum last updated UTC datetime
      - name: last_updated_max
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Maximum last updated UTC datetime
          title: Last Updated Max
        description: Maximum last updated UTC datetime
      - name: _forward
        in: query
        required: false
        schema:
          type: boolean
          description: Whether to page forward (True) or backward (False) in the search results.
          default: true
          title: ' Forward'
        description: Whether to page forward (True) or backward (False) in the search results.
      - name: _pagination_token
        in: query
        required: false
        schema:
          type: string
          description: Pagination token for the next set of results.
          title: ' Pagination Token'
        description: Pagination token for the next set of results.
      - name: _skip
        in: query
        required: false
        schema:
          type: integer
          description: Number of entries to skip in the search.
          default: 0
          title: ' Skip'
        description: Number of entries to skip in the search.
      - name: _limit
        in: query
        required: false
        schema:
          type: integer
          description: Max number of entries to return in a single query. Limited to 1000.
          default: 100
          title: ' Limit'
        description: Max number of entries to return in a single query. Limited to 1000.
      - name: _fields
        in: query
        required: false
        schema:
          type: string
          description: 'Fields to project from TaskDoc 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` `additional_json` `analysis` `author` `calcs_reversed` `custodian` `entry` `included_objects` `run_stats` `state` `task_label`'
          title: ' Fields'
        description: 'Fields to project from TaskDoc 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` `additional_json` `analysis` `author` `calcs_reversed` `custodian` `entry` `included_objects` `run_stats` `state` `task_label`'
      - name: _all_fields
        in: query
        required: false
        schema:
          type: boolean
          description: Include all fields.
          default: false
          title: ' All Fields'
        description: Include all fields.
      responses:
        '200':
          description: Search for a TaskDoc
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response_TaskDoc_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Response_DeprecationDoc_:
      properties:
        data:
          anyOf:
          - items:
              $ref: '#/components/schemas/DeprecationDoc'
            type: array
          - type: 'null'
          title: Data
          description: List of returned data
        errors:
          anyOf:
          - items:
              $ref: '#/components/schemas/Error'
            type: array
          - type: 'null'
          title: Errors
          description: Any errors on processing this query
        meta:
          anyOf:
          - $ref: '#/components/schemas/Meta'
          - type: 'null'
          description: Extra information for the query
      type: object
      title: Response[DeprecationDoc]
    RelaxTrajectory:
      properties:
        elements:
          items:
            type: integer
          type: array
          title: Elements
          description: The proton number Z of the elements in the sites
        cart_coords:
          items:
            anyOf:
            - items:
                prefixItems:
                - type: number
                - type: number
                - type: number
                type: array
                maxItems: 3
                minItems: 3
              type: array
            - type: 'null'
          type: array
          title: Cart Coords
          description: The Cartesian coordinates (Å) of the sites at each ionic step
        num_ionic_steps:
          type: integer
          title: Num Ionic Steps
          description: The number of ionic steps.
        lattice:
          anyOf:
          - items:
              prefixItems:
              - prefixItems:
                - type: number
                - type: number
                - type: number
                type: array
                maxItems: 3
                minItems: 3
              - prefixItems:
                - type: number
                - type: number
                - type: number
                type: array
                maxItems: 3
                minItems: 3
              - prefixItems:
                - type: number
                - type: number
                - type: number
                type: array
                maxItems: 3
                minItems: 3
              type: array
              maxItems: 3
              minItems: 3
            type: array
          - type: 'null'
          title: Lattice
          description: If a list containing only one 3x3 matrix, it is assumed that the lattice was held constant through the simulation. If a list of (multiple) 3x3 matrices, this should be the lattice at each ionic step in the calculation. If None, a non-periodic system is assumed.
        energy:
          anyOf:
          - items:
              type: number
            type: array
          - type: 'null'
          title: Energy
          description: The total energy at each ionic step.
        forces:
          anyOf:
          - items:
              items:
                prefixItems:
                - type: number
                - type: number
                - type: number
                type: array
                maxItems: 3
                minItems: 3
              type: array
            type: array
          - type: 'null'
          title: Forces
          description: The interatomic forces.
        stress:
          anyOf:
          - items:
              prefixItems:
              - prefixItems:
                - type: number
                - type: number
                - type: number
                type: array
                maxItems: 3
                minItems: 3
              - prefixItems:
                - type: number
                - type: number
                - type: number
                type: array
                maxItems: 3
                minItems: 3
              - prefixItems:
                - type: number
                - type: number
                - type: number
                type: array
                maxItems: 3
                minItems: 3
              type: array
              maxItems: 3
              minItems: 3
            type: array
          - type: 'null'
          title: Stress
          description: The 3x3 stress tensor.
        electronic_steps:
          anyOf:
          - items:
              items:
                $ref: '#/components/schemas/ElectronicStep'
              type: array
            type: array
          - type: 'null'
          title: Electronic Steps
          description: The electronic steps within a given ionic step.
        num_electronic_steps:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          title: Num Electronic Steps
          description: The number of electronic steps within each ionic step.
        e_wo_entrp:
          anyOf:
          - items:
              type: number
            type: array
          - type: 'null'
          title: E Wo Entrp
          description: The total energy in eV without electronic pseudoentropy from smearing of the Fermi surface.
        e_fr_energy:
          anyOf:
          - items:
              type: number
            type: array
          - type: 'null'
          title: E Fr Energy
          description: The total electronic free energy in eV.
        identifier:
          anyOf:
          - type: string
          - type: 'null'
          title: Identifier
          description: Identifier of this trajectory, e.g., task ID.
        task_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Task Type
          description: The TaskType of the calculation used to generate this trajectory.
        run_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Run Type
          description: The RunType of the calculation used to generate this trajectory.
      type: object
      required:
      - elements
      - cart_coords
      - num_ionic_steps
      title: RelaxTrajectory
      description: 'Low memory schema for relaxation trajectories that can interface with parquet, pymatgen, and ASE.


        This schema is intended primarily for VASP relaxation trajectories, but could be adapted to

        generic electronic structure trajectories.


        Note that for VASP calculations, energies are in eV, forces in eV/Å, and stress tensors in kilobar.'
    Error:
      properties:
        code:
          type: integer
          title: Code
          description: The error code
        message:
          type: string
          title: Message
          description: The description of the error
      type: object
      required:
      - code
      - message
      title: Error
      description: Base Error model for General API.
    CustodianDoc:
      properties:
        corrections:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Custodian Corrections
          description: List of custodian correction data for calculation.
        job:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Custodian Job Data
          description: Job data logged by custodian.
      type: object
      title: CustodianDoc
    TypedOutcarDict:
      properties:
        '@module':
          type: string
          title: '@Module'
        '@class':
          type: string
          title: '@Class'
        efermi:
          anyOf:
          - type: number
          - type: 'null'
          title: Efermi
        magnetization:
          anyOf:
          - items:
              $ref: '#/components/schemas/TypedPerIonProps'
            type: array
          - type: 'null'
          title: Magnetization
        charge:
          anyOf:
          - items:
              $ref: '#/components/schemas/TypedPerIonProps'
            type: array
          - type: 'null'
          title: Charge
        total_magnetization:
          anyOf:
          - type: number
          - type: 'null'
          title: Total Magnetization
        nelect:
          anyOf:
          - type: number
          - type: 'null'
          title: Nelect
        is_stopped:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Stopped
        drift:
          anyOf:
          - items:
              items:
                type: number
              type: array
            type: array
          - type: 'null'
          title: Drift
        ngf:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          title: Ngf
        sampling_radii:
          anyOf:
          - items:
              type: number
            type: array
          - type: 'null'
          title: Sampling Radii
        electrostatic_potential:
          anyOf:
          - items:
              type: number
            type: array
          - type: 'null'
          title: Electrostatic Potential
        zval_dict:
          anyOf:
          - additionalProperties:
              type: number
            type: object
          - type: 'null'
          title: Zval Dict
        p_elec:
          anyOf:
          - prefixItems:
            - type: number
            - type: number
            - type: number
            type: array
            maxItems: 3
            minItems: 3
          - type: 'null'
          title: P Elec
        born:
          anyOf:
          - items:
              prefixItems:
              - prefixItems:
                - type: number
                - type: number
                - type: number
                type: array
                maxItems: 3
                minItems: 3
              - prefixItems:
                - type: number
                - type: number
                - type: number
                type: array
                maxItems: 3
                minItems: 3
              - prefixItems:
                - type: number
                - type: number
                - type: number
                type: array
                maxItems: 3
                minItems: 3
              type: array
              maxItems: 3
              minItems: 3
            type: array
          - type: 'null'
          title: Born
      type: object
      required:
      - '@module'
      - '@class'
      title: TypedOutcarDict
    Response_EntryDoc_:
      properties:
        data:
          anyOf:
          - items:
              $ref: '#/components/schemas/EntryDoc'
            type: array
          - type: 'null'
          title: Data
          description: List of returned data
        errors:
          anyOf:
          - items:
              $ref: '#/components/schemas/Error'
            type: array
          - type: 'null'
          title: Errors
          description: Any errors on processing this query
        meta:
          anyOf:
          - $ref: '#/components/schemas/Meta'
          - type: 'null'
          description: Extra information for the query
      type: object
      title: Response[EntryDoc]
    BaderAnalysis:
      properties:
        min_dist:
          items:
            type: number
          type: array
          title: Min Dist
        charge:
          items:
            type: number
          type: array
          title: Charge
        atomic_volume:
          items:
            type: number
          type: array
          title: Atomic Volume
        vacuum_charge:
          type: number
          title: Vacuum Charge
        vacuum_volume:
          type: number
          title: Vacuum Volume
        reference_used:
          type: boolean
          title: Reference Used
        bader_version:
          type: number
          title: Bader Version
        charge_transfer:
          anyOf:
          - items:
              type: number
            type: array
          - type: 'null'
          title: Charge Transfer
        magmom:
          anyOf:
          - items:
              type: number
            type: array
          - type: 'null'
          title: Magmom
      type: object
      required:
      - min_dist
      - charge
      - atomic_volume
      - vacuum_charge
      - vacuum_volume
      - reference_used
      - bader_version
      title: BaderAnalysis
      description: 'Output of pymatgen.command_line.bader_caller.bader_analysis_from_objects


        We omit the `charge_densities` field, since these are too large

        to justify storing in the document model.


        Charge densities can already be stored in TaskDoc.vasp_objects'
    SymmetryData:
      properties:
        crystal_system:
          anyOf:
          - type: string
          - type: 'null'
          title: Crystal System
          description: The crystal system for this lattice.
        symbol:
          anyOf:
          - type: string
          - type: 'null'
          title: Space Group Symbol
          description: The spacegroup symbol for the lattice.
        hall:
          anyOf:
          - type: string
          - type: 'null'
          title: Hall Symbol
          description: Hall symbol for the lattice
        number:
          anyOf:
          - type: integer
          - type: 'null'
          title: Space Group Number
          description: The spacegroup number for the lattice.
        point_group:
          anyOf:
          - type: string
          - type: 'null'
          title: Point Group Symbol
          description: The point group for the lattice.
        symprec:
          anyOf:
          - type: number
          - type: 'null'
          title: Symmetry Finding Precision
          description: The precision provided to spglib to determine the symmetry of this structure.
        angle_tolerance:
          anyOf:
          - type: number
          - type: 'null'
          title: Angle Tolerance
          description: Angle tolerance provided to spglib to determine the symmetry of this structure.
        version:
          anyOf:
          - type: string
          - type: 'null'
          title: spglib version
      type: object
      title: SymmetryData
      description: Defines a symmetry data set for materials documents
    TypedLatticeDict:
      properties:
        matrix:
          items:
            items:
              type: number
            type: array
          type: array
          title: Matrix
        pbc:
          anyOf:
          - prefixItems:
            - type: boolean
            - type: boolean
            - type: boolean
            type: array
            maxItems: 3
            minItems: 3
          - type: 'null'
          title: Pbc
        a:
          type: number
          title: A
        b:
          type: number
          title: B
        c:
          type: number
          title: C
        alpha:
          type: number
          title: Alpha
        beta:
          type: number
          title: Beta
        gamma:
          type: number
          title: Gamma
        volume:
          type: number
          title: Volume
      type: object
      required:
      - matrix
      - a
      - b
      - c
      - alpha
      - beta
      - gamma
      - volume
      title: TypedLatticeDict
    RunStatistics:
      properties:
        average_memory:
          type: number
          title: Average Memory
          description: The average memory used in kb
          default: 0
        max_memory:
          type: number
          title: Max Memory
          description: The maximum memory used in kb
          default: 0
        elapsed_time:
          type: number
          title: Elapsed Time
          description: The real time elapsed in seconds
          default: 0
        system_time:
     

# --- truncated at 32 KB (83 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/materials-project/refs/heads/main/openapi/materials-project-materials-tasks-api-openapi.yml