Get Reports

Retrieve a list of all reports that have been submitted for your engaged projects.

Overview

This endpoint returns a list of reports that have been submitted for projects you are actively engaged with. Each report contains trading data including liquidity metrics, order book depth, and trading volumes across different exchanges and trading pairs.

Endpoint: GET https://data.api.forgd.com/api/v1/reports

Authentication: Required (API Key) (docs)

Managing your reports

Read more about how to submit reports in the Report Trading Data section.

GET Request

Headers

Header	Type	Required	Description
`Authorization`	string	Yes	API key for authentication Check Authentication for more details

Query Parameters

Parameter	Type	Required	Description
`baseCoinId`	string	No	Filter reports by base coin ID (e.g., "dogecoin", "solana")
`exchangeId`	string	No	Filter reports by exchange ID (e.g., "binance", "bybit_spot")
`dateGte`	string	No	Filter reports from this date (inclusive) in YYYY-MM-DD format
`dateLte`	string	No	Filter reports to this date (inclusive) in YYYY-MM-DD format
`page`	number	No	Page number for pagination (default: 1)

Examples

javascriptpythoncurl

// Get all reports
const response = await fetch('https://data.api.forgd.com/api/v1/reports', {
  method: 'GET',
  headers: {
    Authorization: '<API_KEY>',
  },
})

// Get reports with filters
const filteredResponse = await fetch(
  'https://data.api.forgd.com/api/v1/reports?baseCoinId=solana&exchangeId=binance&dateGte=2025-01-01&dateLte=2025-01-31&page=1',
  {
    method: 'GET',
    headers: {
      Authorization: '<API_KEY>',
    },
  },
)

const data = await response.json()

if (response.ok) {
  console.log('Reports:', data)
} else {
  console.error('Error:', response.status, response.statusText, data)
}

python

import requests

# Get all reports
response = requests.get(
    'https://data.api.forgd.com/api/v1/reports',
    headers={'Authorization': '<API_KEY>'},
)

# Get reports with filters
params = {
    'baseCoinId': 'solana',
    'exchangeId': 'binance',
    'dateGte': '2025-01-01',
    'dateLte': '2025-01-31',
    'page': 1
}

filtered_response = requests.get(
    'https://data.api.forgd.com/api/v1/reports',
    headers={'Authorization': '<API_KEY>'},
    params=params
)

data = response.json()

if response.ok:
    print('Reports:', data)
else:
    print('Error:', response.status_code, response.reason, data)

bash

# Get all reports
curl -X GET "https://data.api.forgd.com/api/v1/reports" \
  -H "Authorization: <API_KEY>"

# Get reports with filters
curl -X GET "https://data.api.forgd.com/api/v1/reports?baseCoinId=solana&exchangeId=binance&dateGte=2025-01-01&dateLte=2025-01-31&page=1" \
  -H "Authorization: <API_KEY>"

Success Response

HTTP 200 OK

Returns a paginated response containing report objects. Each report object contains trading data for a specific date, exchange, and trading pair.

Response Type

Response TypeResponse Example JSON

type SuccessResponseType = {
  page: number
  totalPages: number
  totalCount: number
  items: {
    date: string
    exchangeId: string
    exchangeName: string
    baseCoinId: string
    baseCoinSymbol: string
    quoteCoinId?: string
    quoteCoinSymbol?: string
    bidDepth50?: number
    askDepth50?: number
    bidAskDepth50?: number
    bidDepth100?: number
    askDepth100?: number
    bidAskDepth100?: number
    bidDepth200?: number
    askDepth200?: number
    bidAskDepth200?: number
    bidAskSpread?: number
    orderFillVolumeMaker?: number
    orderFillVolumeTaker?: number
    eligibilityStatus: string
  }[]
}

json

{
  "page": 1,
  "totalPages": 1,
  "totalCount": 2,
  "items": [
    {
      "date": "2025-01-01",
      "exchangeId": "binance",
      "exchangeName": "Binance",
      "baseCoinId": "dogecoin",
      "baseCoinSymbol": "DOGE",
      "quoteCoinId": "tether",
      "quoteCoinSymbol": "USDT",
      "bidDepth50": 809,
      "askDepth50": 971,
      "bidAskDepth50": 1780,
      "bidDepth100": 1380,
      "askDepth100": 1520,
      "bidAskDepth100": 2900,
      "bidDepth200": 2180,
      "askDepth200": 2320,
      "bidAskDepth200": 4500,
      "bidAskSpread": 0.1,
      "orderFillVolumeMaker": 8902,
      "orderFillVolumeTaker": 23479,
      "eligibilityStatus": "eligible"
    },
    {
      "date": "2025-01-02",
      "exchangeId": "binance",
      "exchangeName": "Binance",
      "baseCoinId": "dogecoin",
      "baseCoinSymbol": "DOGE",
      "quoteCoinId": "tether",
      "quoteCoinSymbol": "USDT",
      "bidDepth50": 456,
      "askDepth50": 523,
      "bidAskDepth50": 979,
      "bidDepth100": 789,
      "askDepth100": 856,
      "bidAskDepth100": 1645,
      "bidDepth200": 1245,
      "askDepth200": 1321,
      "bidAskDepth200": 2566,
      "bidAskSpread": 0.15,
      "orderFillVolumeMaker": 5432,
      "orderFillVolumeTaker": 15678,
      "eligibilityStatus": "eligible"
    }
  ]
}

Pagination

The reports endpoint supports pagination to handle large datasets efficiently. Results are limited to 500 items per page. The response includes:

page: Current page number
totalPages: Total number of pages available
totalCount: Total number of reports across all pages
items: Array of reports for the current page

To navigate through pages, use the page query parameter:

bash

# Get first page
curl -X GET "https://data.api.forgd.com/api/v1/reports?page=1"

# Get second page
curl -X GET "https://data.api.forgd.com/api/v1/reports?page=2"

Ordering

Reports are returned in a specific order to ensure consistent results:

Date: Descending order (newest reports first)
Exchange ID: Ascending order (alphabetical)
Base coin ID: Ascending order (alphabetical)

This ordering ensures that the most recent reports appear first, and when multiple reports exist for the same date, they are consistently ordered by exchange ID and base coin ID.

Error Responses

HTTP 401 Unauthorized

The request could not be authenticated. Possible reasons:

You have not attached an API Key to your request - see Authentication
Your API key is invalid or has been removed - see Obtaining an API Key

Response TypeResponse Example JSON

type ErrorResponseType = {
  message: string
  statusCode: number
}

json

{
  "message": "Unauthorized",
  "statusCode": 401
}

HTTP 5xx Internal Server Error

The request has failed due to an error on the server side. Most likely there is an internal issue with our server or network - please try again after couple of minutes.

We are getting notified about every 5XX response internally but if this is an recurring issue, please contact us at support@forgd.com.

FAQ & Troubleshooting

I can't find my reports

This endpoint returns only reports that have been submitted for projects with active engagement with your organization. Please make sure that:

The project you are looking for is present in "My Engagements" section of the Forgd Liquidity Portal
You have submitted reports for that project using the Report Trading Data endpoint

Reports for projects without active engagement will not be included in the response.

How to submit new reports

Read more about how to submit trading data reports in the Report Trading Data section.

Understanding report data fields

Each report contains trading metrics for a specific date, exchange, and trading pair:

Depth metrics: bidDepth50, askDepth50, bidAskDepth50, etc. represent order book depth at different tick levels (in USD)
Spread: bidAskSpread represents the bid-ask spread as a percentage (e.g., 0.5 for 0.5%)
Volume: orderFillVolumeMaker and orderFillVolumeTaker represent trading volumes in USD
Exchange info: exchangeId and exchangeName identify the exchange where the data was collected
Coin info: baseCoinId, baseCoinSymbol, quoteCoinId, and quoteCoinSymbol identify the trading pair
Eligibility: eligibilityStatus indicates whether the report meets eligibility requirements (see eligibility status FAQ)

Filtering reports

You can filter reports using query parameters:

By project: Use baseCoinId to filter reports for a specific project (e.g., "solana", "dogecoin")
By exchange: Use exchangeId to filter reports from a specific exchange (e.g., "binance", "bybit_spot")
By date range: Use dateGte and dateLte to filter reports within a specific date range
Pagination: Use page to navigate through large result sets

Working with pagination

When you have many reports, the API returns them in pages. Check the totalPages field to see how many pages are available, and use the page parameter to navigate through them.

Understanding eligibility status

The eligibilityStatus field indicates whether a report meets the requirements for market data validation:

eligible: The report is valid and has been successfully matched with market data
ineligible_market_data_missing: The report could not be validated due to missing market data

Reports become ineligible when:

No market data for the exchange: We don't have market data collected for the specified exchange
Coin not listed on exchange: The base coin is not available for trading on the specified exchange
Trading pair not found: The specific trading pair (base/quote combination) doesn't exist on the exchange
Date before engagement: The report date is before market data collection started for this trading pair (market data collection typically begins when an engagement is created)

To ensure your reports are eligible, make sure you're submitting data for:

Valid exchanges that we monitor
Coins that are actually traded on those exchanges
Trading pairs that exist on the exchange
Dates after your engagement was established

Get Reports ​

Overview ​

GET Request ​

Headers ​

Query Parameters ​

Examples ​

Success Response ​

HTTP 200 OK ​

Response Type ​

Pagination ​

Ordering ​

Error Responses ​

HTTP 401 Unauthorized ​

HTTP 5xx Internal Server Error ​

FAQ & Troubleshooting ​

I can't find my reports ​

How to submit new reports ​

Understanding report data fields ​

Filtering reports ​

Working with pagination ​

Understanding eligibility status ​