---
title: "Get tier-n collection supplier graph"
method: GET
path: "/public/v1/collections/{collectionId}/tier-n/data"
tags: ["Collections - Tier-N"]
---

# Get tier-n collection supplier graph

`GET /public/v1/collections/{collectionId}/tier-n/data`

### Overview
Retrieve a stream of supplier relationship data for a tier-n enabled collection.

**Effective tier** = `tier` if provided, otherwise `maxTier` (request override, else collection setting, else 1). That value selects the response mode:
- **Effective tier = 1**: Collection membership rows only — each supplier in the collection with the customer organization as `customerTargetId`. Edge/discovery fields (`source`, `probability`, `mediaSources`, `nShipments`, `shipments`) are null and omitted from JSON.
- **Effective tier ≥ 2**: Membership rows first (same shape as tier 1), then suppliers discovered via tier-n traversal from collection members. Relative to each collection member: response `tier` 1 = that member's direct suppliers, tier 2+ = indirect (suppliers of suppliers). Distinguish membership from traversal `"tier": 1` by `customerTargetId` = organization and `source` omitted/null.

**Request `tier` vs response `tier`:** In traversal rows, response `tier` is relative to each collection member — not a copy of the request parameter. Example: `?tier=3` can still return traversal rows with `"tier": 1` (a collection member's direct supplier). Membership rows always use `"tier": 1` with the organization as `customerTargetId`.

### Examples
- `GET .../tier-n/data?tier=1` → membership only (see "Membership" example): `[{ "tier": 1, "supplierTargetId": …, "customerTargetId": <organizationId> }, …]`
- `GET .../tier-n/data?tier=3` → membership first, then traversal up to tier 3 relative to collection members (see "Traversal" example); e.g. membership `"tier": 1` with organization as `customerTargetId`, then traversal `"tier": 1` = that member's direct suppliers, `"tier": 2` = indirect, and so on
- Omitting `tier` uses `maxTier` (query override, else collection setting, else 1). If that resolves to 1, you get membership only — common when the collection's `maxTier` is 1

### Response Format
- JSON array of entries (`tier`, `supplierTargetId`, `customerTargetId`, and optional `source` / probability / media / shipment fields).
- Null-valued fields are omitted. Optional edge fields appear based on query params only on traversal rows (e.g. `includeMediaSources`, `includeShipmentDetails`). Membership rows have no edge data.

### Query Parameters
All optional. They override collection defaults from `GET .../tier-n/settings`.
- At **effective tier = 1**, filter and include parameters (`source`, `hsCodes`, `lastShipment`, `includeMediaSources`, `includeShipmentDetails`, scope/source overrides, etc.) are **ignored** — the response is always unfiltered membership.
- At **effective tier ≥ 2**, those parameters apply to discovered (traversal) relationships only; membership rows remain unfiltered.

### Performance
- For traversal, filter by `source` or `hsCodes` to reduce response size. Higher effective tier / `maxTier` increases data volume and response time.

### Related Operations
- **Settings**: [GET /public/v1/collections/{collectionId}/tier-n/settings](#operations-Collections_-_Tier-N-getTierNCollectionSettings)
- **Update settings**: [PUT /public/v1/collections/{collectionId}/tier-n/settings](#operations-Collections_-_Tier-N-updateTierNCollectionSettings)

### Required Permission
`access_public_supplier_graph`, `access_collection`, and `read` on the collection.

## Path parameters

- `collectionId` integer, required

## Query parameters

- `includeCommodityFilter` boolean — Include commodity filter metadata in the response. When true, adds commodity filter information to help understand data scope and filtering applied.
- `includeMediaSources` boolean — Include media source URLs for MEDIA-type relationships (traversal only; ignored when effective tier = 1). When true, adds `mediaSources` array with URLs used to derive the relationship from news/media sources.
- `includeShipmentDetails` boolean — Include detailed shipment information per HS code (traversal only; ignored when effective tier = 1). When true, adds `shipments` array with shipment counts and dates broken down by product code.
- `tier` integer — Sets the effective tier when provided (otherwise effective tier = maxTier). Effective tier 1 = collection membership only (edge fields omitted; other query filters ignored). Effective tier ≥ 2 = membership rows first, then traversal; traversal response `tier` is relative to each collection member (1 = that member's direct suppliers, 2+ = indirect), not a copy of this parameter. Range: 1-9.
- `source` 'Customer' | 'Media' | 'Customs' | 'PrewavePrediction'
- `lastShipment` string — Only include suppliers with shipments since this date (traversal only; ignored when effective tier = 1). Format: YYYY-MM-DD.
- `hsCodes` string — Filter by specific HS codes, comma-separated (traversal only; ignored when effective tier = 1). Example: 847330,940161
- `maxTier` integer — Override the collection maxTier setting. When `tier` is omitted, this value is also the effective tier (1 = membership only with other filters ignored; ≥ 2 = membership plus traversal up to that tier relative to collection members). Higher values may increase response time and data volume. Range: 1-9.
- `scopePrivate` boolean — Override collection setting: include private targets in scope. When true, includes relationships involving private targets (typically internal company data).
- `scopeShared` boolean — Override collection setting: include shared targets in scope. When true, includes relationships involving shared targets (typically partner/team data).
- `scopePublic` boolean — Override collection setting: include public targets in scope. When true, includes relationships involving public targets (typically open/public data).
- `sourceCustomer` boolean — Override collection setting: include customer data sources. When true, includes relationships derived from customer-provided data.
- `sourceCustoms` boolean — Override collection setting: include customs data sources. When true, includes relationships derived from customs/shipment data (most reliable source).
- `sourceMedia` boolean — Override collection setting: include media data sources. When true, includes relationships derived from media/news sources (may be less reliable).
- `sourcePrewavePrediction` boolean — Override collection setting: include Prewave prediction data sources. When true, includes AI-predicted relationships with probability scores.
- `minShipments` integer — Override collection setting: minimum number of shipments required for a relationship to be included. Higher values filter out less established relationships. Range: 0+.
- `probability` integer — Override collection setting: minimum probability threshold for predicted relationships. Range: 0-100. Higher values return only high-confidence predictions.
- `shipmentsPeriodFrom` string — Override collection setting: start date for shipment period analysis. Format: YYYY-MM-DD. Only relationships with shipments in this period are considered.
- `shipmentsPeriodTo` string — Override collection setting: end date for shipment period analysis. Format: YYYY-MM-DD. Only relationships with shipments in this period are considered.
- `suspectedSuppliers` boolean — Override collection setting: include suspected suppliers. When true, includes suppliers flagged as potentially risky or suspicious.
- `logisticsProvider` boolean — Override collection setting: include logistics providers. When true, includes companies that provide logistics services rather than direct suppliers.

## Response `200`

Successfully retrieved tier-n collection supplier graph.

- PublicTierNCollectionGraphEntry[]
  - `tier` integer, required — Tier level. Membership rows: always 1. Traversal rows: relative to each collection member (1 = that member's direct suppliers, 2+ = indirect). For traversal rows this is not the same as the request `tier` parameter (which selects membership-only vs membership+traversal / max depth).
  - `supplierTargetId` integer, required — Unique identifier of the supplier target in this relationship. Use this ID to look up additional supplier information via other APIs.
  - `customerTargetId` integer, required — Unique identifier of the customer target in this relationship. The 'from' side of the relationship (customer organization for membership rows; upstream target for traversal rows).
  - `source` 'Customer' | 'Media' | 'Customs' | 'PrewavePrediction'
  - `probability` integer, nullable — Confidence or probability score for the relationship (0-100). Only present for PREWAVE_PREDICTION sources. Higher values indicate more confident predictions.
  - `mediaSources` string[], nullable — List of media source URLs used to derive this MEDIA-type relationship. Only present when source=MEDIA and includeMediaSources=true. These URLs provide evidence for the relationship.
  - `nShipments` integer, nullable — Number of shipments observed for this supplier/customer pair. Only present for CUSTOMS sources. Indicates the strength of the business relationship based on trade data.
  - `shipments` PublicTierNCollectionGraphShipment — Detailed shipment information for a specific HS code within a supplier relationship. This provides granular shipment data broken down by product category (HS code), showing the volume and recency of trade activity for specific products between the supplier and customer. ## HS Codes HS (Harmonized System) codes are 6-digit product classification codes used internationally for trade. They help identify specific product categories involved in the business relationship. ## Use Cases - **Product Analysis**: Understand which products drive the relationship - **Volume Assessment**: See shipment frequency and volume per product - **Recency Tracking**: Identify the most recent activity per product - **Risk Analysis**: Assess dependency on specific product categories
    - `hscode` integer, required — 6-digit HS (Harmonized System) code identifying the product category. Used internationally for trade classification.
    - `nShipments` integer, nullable — Number of shipments observed for this specific HS code in the relationship. Indicates the volume of trade activity for this product category.
    - `lastShipment` string, date, nullable — Date of the most recent shipment observed for this HS code. Format: YYYY-MM-DD. Useful for assessing recency of product-specific activity.
    - `nshipments` integer
  - `nshipments` integer

## Other responses

- `400` — Collection not tier-n enabled or invalid parameters (e.g. tier/maxTier out of range).
- `403` — 403 Forbidden - Authentication or authorization failure. This status code is returned when: (1) the request lacks valid authentication credentials (missing or invalid X-Auth-Token header), or (2) the authenticated user does not have the required permission to access this resource.
- `404` — Collection not found, inactive, not tier-n enabled, or not accessible.
- `429` — 429 Too Many Requests - API rate limit exceeded. The request has been rejected because the rate limit for this endpoint has been exceeded. Default rate limits: GET requests - 100 per 10 seconds, 500 per minute; POST/PUT/PATCH/DELETE requests - 20 per 10 seconds, 100 per minute. For increased access, please contact customer success.
- `500` — 500 Internal Server Error - An unexpected error occurred on the server. The request may or may not have been processed.

---

[API](https://skmtc.net/prewave/apis/public-prewave-api.md) · [All operations](https://skmtc.net/prewave/apis/public-prewave-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/prewave/public-prewave-api/revisions/466169815b78/schema)