Metadata Rest Endpoints

Common Aspects


The Metadata REST API allows EGA users to request metadata from the EGA.
Using this api you will be able to obtain the publicly available information from EGA study, sample, experiment, run, analysis, policy, dac and dataset. The API also allows for objects to be cross-referenced in order to obtain for example all the datasets linked to a dac.


EGA objects can be identified by their unique accession. These are ID's displayed everywhere, shared among all EGA locations and specific for each data type (More information on the list below)

  Accession ID
  EGA Object description
EGAS EGA Study Accession ID
EGAP EGA Policy Accession ID
EGAN EGA Sample Accession ID
EGAR EGA Run Accession ID
EGAX EGA Experiment ID
EGAZ EGA Analysis Accession ID
EGAD EGA Dataset Accession ID
EGAB EGA Submission ID
EGAF EGA File Unique Accession ID


Server Response

Understanding the server Responses

The server response is divided within 2 main sections they are the header and response.

  • "header"
    • Contains information about the HTTP connection
    • "code"
      • Please see more about response codes on the table below
  • "response"
    • Is the container for the response
    • "numTotalResults"
      • By default, only 10 results are shown.
      • This field tells you if there are more results hidden (e.g. if the user asks for all the samples, there might be hundreds or thousands)
    • "resultType"
      • The type of the objects returned (e.g. sample, dac, dataset, etc.).
    • "result"
      • The list of objects returned.

HTTP response codes

API responses are diverse but they always return a status call. Below you have a summary on what these codes mean and some tips that can help you troubleshooting them:

  HTTP Status
  Description   Resolution
200 OK No error handling necessary
400 BAD REQUEST Request incorrectly formulated
401 UNAUTHORIZED/FORBIDDEN You do not have permissions over the object you are trying to access. / The authorized user is not permitted to make the given request.
404 NOT FOUND The object /resource you are trying to access does not exist.
500 INTERNAL SERVER ERROR This is a server-side error. Contact the Heldpesk to notify the issue.


Querying by Object

In the below documentation, worked examples can be found on how to use the API, to query about each unique EGA object.{id}{id}{id}?idType=EGA_STABLE_ID{id}{id}{id}

Worked example for the EGA data access committee(DAC) EGAC00001000514

Points to notice

Please, be advised that all EGA objects can be queried by using the same endpoint (this will return by default 10 results per page). For example:

Returns 10 results.

Returns 5 results skipping the initial 15 results. Notice that “skip” needs to be multiple of “limit” in order to display new results

Cross-Querying by Object

The EGA REST API Metadata also allows for the crossquerying of public metadata.

For example, should I want to query the datasets included in the ICGC DAC:  
Below, you can find worked examples on how to perform the call to the API. 

Points to notice

All objects can be returned from a cross query by adding &limit=0. For example:"

There are more endpoints included in this category. Please, find all the possibilities (green tick) in the table below.


The table displays in a ordered fashion the objects that can be crossreferenced using the metadata API.

  TO   Analysis   Dac   Dataset   Experiment   Policy   Run   Sample   Study   Submission   File