To authenticate with the Skylight API, you will need to include a valid Skylight username and password in a getToken request:

curl -X POST \
    -H "Content-Type: application/json" \
    -d '{"query":"{getToken(username: \"YOUR_SKYLIGHT_USERNAME\", password: \"YOUR_SKYLIGHT_PASSWORD\") \
    {access_token expires_in}}"}' \
    https://api.skylight.earth/graphql

The response will contain an access_token value to be used in subsequent API requests:

{
  "data": {
    "getToken": {
      "access_token": "YYOdIqB48ZDS3OJpWHJxrjku1Gh0Yl",
      "expires_in": 86400
    }
  }
}

Once you have an access_token, you can use it to authenticate your requests by including the access token in the Authorization header:

curl -X POST \
    -H 'Authorization: Bearer $ACCESS_TOKEN' \
    -H "Content-Type: application/json" \
    -d '{"query":"{vessel(vesselId: \"B:735058020:1719441624:822782:817302\"){vessel_id flag flag_code mmsi}}"}' \
    https://api.skylight.earth/graphql

Access tokens are valid for 24 hours from the time of issue. Requesting a new access token will automatically revoke any previously issued tokens.

---

Skylight aims to make data available as soon as possible after receiving it. In order to optimize for this near-real-time use case, we only store data for 540 days (approximately 18 months) after which we delete it.

To support this, our APIs enforce that your query does not request data older than 540 days.

Many clients of Skylight want to be able to quickly visualize large amounts of geospatial data on a map. One way to do this efficiently is to use vector tiles. The Skylight API in particular supports the use of Mapbox Vector Tiles for several of our datasets.

The Vector Tile APIs use the same request object structure as their corresponding GraphQL APIs, but the response is formatted in a protobuf encoded vector tile of the geometry features with a subset of the properties attached to each feature. For vector tile APIs, submit the request query as a json encoded string in the query parameter in the URL.

The following rules apply to all vector tile endpoints:

• Path Parameters z, x, y: These represent the grid location of the tile being requested. These values will typically be provided by your mapping library. These values are used to determine the bounding box of the tile being requested, and replace the intersectsGeometry parameter in the GraphQL API. You cannot use the intersectsGeometry parameter when requesting vector tiles.
• Query Parameters limit, offset, sortBy, and sortDirection: These parameters are not available for vector tile requests, as vector tiles always include all features within that tile, and the results are unsorted.

Event Vector Tiles

• URL: https://api.skylight.earth/vectorTiles/eventsV2/{z}/{x}/{y}
• Corresponding GraphQL API: searchEventsV2.
• Vector Tile Restrictions: Due to the extremely large nature of this dataset, all queries must be EITHER:
  • Limited to a specific vessel via the vesselId, mmsi, or trackId filters on vesselMain.
  • OR, limited in duration to 30 days or less via the startTime and endTime parameters.

An example query and the resulting vector tile visualized in Skylight:

curl --get "https://api.skylight.earth/vectorTiles/eventsV2/6/47/34" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
--data-urlencode 'query={
  "startTime":{
    "gte":"2025-01-28T19:43:48.029Z",
    "lte":"2025-01-30T19:43:48.029Z"
  },
  "eventType":{
    "inc":[
       "standard_rendezvous","dark_rendezvous","fishing_activity_history",
       "viirs","sar_sentinel1","eo_sentinel2","eo_landsat_8_9"
    ]
  }
}'

Satellite Frame Vector Tiles

• URL: https://api.skylight.earth/vectorTiles/satelliteFrames/{z}/{x}/{y}
• Corresponding GraphQL API: searchSatelliteFramesV2.
• Vector Tile Restrictions: All queries MUST include a time filter on collectedAt, createdAt or updatedAt. This time range must be 30 days or less.

An example query and the resulting vector tile visualized in Skylight:

  curl --get "https://api.skylight.earth/vectorTiles/satelliteFrames/5/31/15" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --data-urlencode 'query={
    "collectedAt":{"gte":"2025-03-08T17:51:27.082Z","lte":"2025-03-09T17:51:27.082Z"},
    "eventType":{"inc":["sar_sentinel1","eo_sentinel2","eo_landsat_8_9"]},
    "status":{"eq":"Completed"}
  }'

---

There are two ways to paginate through datasets using the Skylight API:

1. Search After (Recommended)

Search After is a methodology of paginating by using a field with a unique and sortable value, and paginating by using the sort field as a filter in future queries. For example to search for all events that occurred on September 1st, 2024, you would apply a date filter to the startTime field, and sort the results by created in ascending order. After each page, update the created.gt filter to the created of the last record in the previous page.

searchEventsV2(input: {
    startTime: { gte: "2024-09-01T00:00:00Z", lt: "2024-09-02T00:00:00Z"},
    sortBy: created,
    sortDirection: asc
}) {
    records {
        events {
            eventId
            created
        }
    }
}

And then find the maximum created timestamp from the first page and use that as the created.gt value for the next page:

searchEventsV2(input: {
    startTime: { gte: "2024-09-01T00:00:00Z", lt: "2024-09-02T00:00:00Z"},
    created: { gt: "2024-09-01T01:12:34Z"},
    sortBy: created,
    sortDirection: asc
}) {
    records { 
        events {
            eventId
            created
        } 
    }
}

2. Limit / Offset

We do also support traditional paginating through datasets with limit and offset parameters. However, we restrict limit + offset to 10,000 records, and performance of those later queries will degrade as the offset increases. We recommend using Search After if you are loading all pages in a programmatic way. Limit / Offset can be more appropriate for User Interfaces where a user is manually paginating through the data, and likely to only look at a few pages.

searchEventsV2(input: {
startTime: { gte: "2024-09-01T00:00:00Z", lt: "2024-09-02T00:00:00Z"},
limit: 100,
offset: 400
}) {
    records { /* Your fields here */ }
}

Using Snapshots for Consistent Pagination

Several datasets within Skylight are updated at a very high frequency and so paginating may result in missing or duplicated results dependent on the paging strategy. To provide a consistent snapshot of the data, we expose a snapshotId field on these datasets to request the backend database to provide a consistent snapshot of the data.

For the first request, send the value of "true" for the snapshotId field to request a new snapshot. The snapshotId will be returned in the meta.snapshotId field of the response:

searchEventsV2(input: {
    startTime: { gte: "2024-09-01T00:00:00Z", lt: "2024-09-02T00:00:00Z"},
    snapshotId: "true"
}) {
    records { /* Your fields here */ }
    meta { snapshotId }
}

For subsequent requests, use the snapshotId value returned in the meta.snapshotId:

searchEventsV2(input: {
    startTime: { gte: "2024-09-01T00:00:00Z", lt: "2024-09-02T00:00:00Z"},
    snapshotId: "1234567890"
}) {
    records { /* Your field here */ }
    meta { snapshotId }
}

A snapshot is kept open for 1 minute after a request, as long as you are making additional requests with the same snapshotId the snapshot will remain open. If you do not make a request within 1 minute, the snapshot will be be closed.

Snapshots are only available on frequently updated datasets that contain the snapshotId field in the input of the search query. If the snapshotId field is not present in the input, then the dataset does not support snapshots.

This change log tracks updates to the Skylight API.

August 12, 2025

• Added new endpoint searchVessels which replaces the vessels endpoint and provides significantly more capabilities for searching vessels.

March 10, 2025

• Added new endpoint searchSatelliteFramesV2 which replaces the satelliteFrames and satelliteFrame endpoint.
• Added a new field distanceToCoastM to ImageryMetadataEventDetails, and the corresponding search input field eventDetails.detectionDistanceToCoastM to EventDetailsFilter. This field is available on Sentinel1, Sentinel2, Landsat 8/9, and VIIRS detection events going forward.
• Added documentation on Skylight's data retention policy.

March 5, 2025

• Removed the deprecated value detection from the EventType enum (for specific detection event types, use the satellite-specific event type: viirs, sar_sentinel1, eo_sentinel2, eo_landsat_8_9).

January 28, 2025

• Added new endpoint searchEventsV2 which replaces the events endpoint. Including the corresponding vector tile endpoint

November 13, 2024

• Added documentation for how to paginate through large result sets.

October 28, 2024

• Added support for vector tile response format for selected endpoints (as an alternative to the default JSON response format).