Skip to main content
To make API calls you will need to have a ClientId and ClientSecret provisioned by the Ginkgo Biosecurity team.

​
Authentication

The Horizon API uses an OAuth2.0 flow for authentication and access control. Each Horizon API user will be provided with a ClientId and ClientSecret that will be used to request an authorization token. Authorization tokens are valid for 24 hours before expiring. A new authorization token can be requested as often as you want, and in general it is recommended that you request a new token for every “session” rather than persisting the token and handling its expiration.

​
Content types

The Ginkgo Biosecurity API always returns JSON in the response bodies.

​
Pagination

Some API endpoints require using pagination to retrieve all the records due to the dataset size. Our v1 and v2 APIs differ in their pagination schemes. It is recommended to use v2 paginated APIs for all use cases due to their consistent API performance when paging through large datasets.

​
V1 Pagination (offset-based)

​
How it Works

V1 endpoints use offset-based pagination with the following parameters:
  • offset: Starting position (0-based index) for the first record to return
  • num: Maximum number of records to return (1-1000)

​
Example Usage

# Get first 100 records
GET /v1/hed-outbreaks/outbreaks?offset=0&num=100

# Get next 100 records (records 101-200)
GET /v1/hed-outbreaks/outbreaks?offset=100&num=100

# Get records 201-300
GET /v1/hed-outbreaks/outbreaks?offset=200&num=100

​
Response Format

V1 paginated endpoints return a simple array of records: 
[
  {
    "id": 1,
    "event": "COVID-19_China_2019",
    "pathogen": "SARS-CoV-2",
    // ... other fields
  },
  {
    "id": 2,
    "event": "Ebola_Democratic_Republic_of_Congo_2018",
    "pathogen": "Ebola virus",
    // ... other fields
  }
  // ... more records
]

​
V2 Pagination (cursor-based)

​
How it Works

V2 endpoints use cursor-based pagination with the following parameters:
  • page: Opaque cursor string for pagination (omit for the first page)
  • num: Maximum number of records to return (1-1000)

​
Example Usage

# Get first page
GET /v2/hed-outbreaks/outbreaks?num=100

# Get next page using cursor from previous response
GET /v2/hed-outbreaks/outbreaks?page=eyJpZCI6MTIzfQ==&num=100

​
Response Format

V2 paginated endpoints return a structured response with pagination metadata: 
{
  "data": [
    {
      "id": 1,
      "event": "COVID-19_China_2019",
      "pathogen": "SARS-CoV-2",
      // ... other fields
    },
    {
      "id": 2,
      "event": "Ebola_Democratic_Republic_of_Congo_2018",
      "pathogen": "Ebola virus",
      // ... other fields
    }
    // ... more records
  ],
  "has_more": true,
  "next_page": "eyJpZCI6MTIzfQ=="
}

​
Response Fields

  • data: Array of records for current page
  • has_more: Boolean indicating if more pages are available
  • next_page: Cursor string for the next page (null if no more pages)