--- 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` ## Request - Base URL: `https://api.prewave.com` - URL: `https://api.prewave.com/public/v1/collections/{collectionId}/tier-n/data` - Auth: API key in header `X-Auth-Token` - TypeScript: (a function with typed inputs; its response is checked against the schema) ### 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": }, …]` - `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: Deprecated. Whether to include suspected suppliers. Ignored, and suspected suppliers are always turned off, when the new commodity filter is enabled for your organization, which will become the default for all organizations. - `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. ## Changes - **2026-10-30** `ecd3f30c3c00`: 1 info - `query` request parameter `suspectedSuppliers` was deprecated [Operation history](https://skmtc.dev/prewave/apis/public-prewave-api/changes/public/v1/collections/:collectionId/tier-n/data/get.md) --- [API](https://skmtc.dev/prewave/apis/public-prewave-api.md) - [All operations](https://skmtc.dev/prewave/apis/public-prewave-api/llms.txt) - [OpenAPI document](https://skmtc.dev/prewave/apis/public-prewave-api/revisions/04221a285ed9?raw)