> ## Documentation Index > Fetch the complete documentation index at: https://terminal49-feat-trade-intel-sdk.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Look up a container's import record > Get the most recent US import of a container from US Customs manifests: bills of lading, carrier, vessel, ports, destination, parties, and commodity lines. ## OpenAPI ````yaml post /trade_intel/containers/lookup openapi: 3.0.0 info: title: Terminal49 API Reference version: 0.2.0 contact: name: Terminal49 API support url: https://www.terminal49.com email: support@terminal49.com description: >- The Terminal 49 API offers a convenient way to programmatically track your shipments from origin to destination. Please enter your API key into the "Variables" tab before using these endpoints within Postman. x-label: Beta termsOfService: https://www.terminal49.com/terms servers: - url: https://api.terminal49.com/v2 description: Production security: - authorization: [] tags: - name: Containers - name: Custom Field Definitions - name: Custom Field Options - name: Custom Fields - name: Shipments - name: Locations - name: Events - name: Tracking Requests - name: Webhooks - name: Webhook Notifications - name: Ports - name: Metro Areas - name: Terminals - name: Routing (Paid) - name: Documents - name: Email Submissions - name: Document Schemas - name: Search - name: Parties - name: Trade Intelligence description: >- Trade intelligence answers questions about who imports what into the US, from where, on which carriers, and how that changes over time. The data is US import bill-of-lading records (US Customs vessel manifests): every ocean container landed at a US port (plus US-bound cargo landed at Vancouver, BC) from January 2022 to today, refreshed daily. It does not include air freight, exports, or domestic moves. **Access.** Trade intelligence is enabled per account. Accounts without it receive `403 Forbidden` with `{"error": "Trade intelligence is not enabled for this account"}`; contact sales@terminal49.com to enable it. Requests are limited to roughly 120 per minute per account (`429` with `{"error": "Rate limit exceeded; retry in a minute"}`). **Format.** These endpoints accept and return plain JSON, not JSON:API. Send `Content-Type: application/json` on `POST` requests and authenticate exactly like every other v2 endpoint (`Authorization: Token YOUR_API_KEY`). **Typical flow.** Resolve a name or product first, then analyze: `companies/search` or `commodities/search` give you the exact `company_name` or `hs4` to pass to `companies/profile`, `importers/top`, `trends`, or `breakdown`. Container and bill of lading numbers go straight to `containers/lookup` and `bills_of_lading/lookup`. **Reading the numbers.** - **Volume is physical containers.** Each box is counted once, even when it appears on several bills of lading. A container carrying several HS codes counts once per code and companies can share containers, so do not add volumes across HS codes or companies; take market totals from `trends` or `breakdown` without a company filter. - **Estimated value is a modelled USD estimate**, not the declared customs value. - **The current month is partial.** `trends` and `breakdown` include it by default; `companies/profile` and `importers/top` use full calendar months. Compare full months against the same months a year earlier. - **Absent volume is not small volume.** Importers can ask US Customs to withhold their name from manifests, and much large-retail freight is booked under forwarders or suppliers. Treat a company's figures as a floor, never as its size. - **One company, many names.** Company names are normalized but split by state, and large importers use several names (distribution, merchandising, and DC entities). Related entities are separate companies; report them separately. `companies/search` ranks by match quality, not by size. - **Companies are the consignee or notify party on the bill.** Forwarders, NVOCCs, and customs brokers appear alongside cargo owners. A high notify-party share, or LOGISTICS, FREIGHT, SHIPPING, CUSTOMS, or BROKERAGE in the name, usually indicates a logistics provider. - **Carriers, countries, and ports use the manifests' spellings**, and carriers appear under spelling variants (for example `CMA CGM` and `CMA CGM AMERICA LLC`). Filter with substrings and merge variants before computing shares. - **HS4 descriptions are truncated.** Check `common_goods` from `commodities/search` before relying on a code. paths: /trade_intel/containers/lookup: post: tags: - Trade Intelligence summary: Look up a container's import record description: >- The most recent US import of a container from US import bill-of-lading records (US Customs vessel manifests): the bills of lading it travelled under (carrier, vessel, voyage, ports, destination) and the commodity lines on those bills with consignee, shipper, and notify party. Only the most recent US import per container is on record; earlier trips are not returned. A malformed number returns `200` with `found: false` and an `error`; a well-formed number with no record returns `found: false`. Commodity lines are capped at 200 (`commodities_truncated`). This lookup reads record-level data and can take several seconds. operationId: post-trade-intel-containers-lookup requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TradeIntelContainerLookupRequest' examples: Container number: value: container_number: MSCU1234567 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/TradeIntelContainerLookup' example: container_number: MSCU1234567 found: true latest_import: container_number: MSCU1234567 imported_on: '2026-08-14' scac: MSCU vessel_name: EXAMPLE VESSEL port_of_discharge_name: LOS ANGELES bills_of_lading: - imported_on: '2026-08-14' master_bill_of_lading_number: MEDUW9559867 house_bill_of_lading_number: null scac: MSCU scac_name: MEDITERRANEAN SHIPPING COMPANY vessel_name: EXAMPLE VESSEL voyage_number: 026N port_of_lading_name: NINGBO port_of_lading_country: PEOPLES REP OF CHINA port_of_discharge_name: LOS ANGELES destination_city: ONTARIO destination_state: CA ultimate_origin_country: PEOPLES REP OF CHINA container_type_short_description: 40 HC container_teu: 2 container_reefer_flag: false commodities: - imported_on: '2026-08-14' master_bill_of_lading_number: MEDUW9559867 house_bill_of_lading_number: null consignee: EXAMPLE OUTDOOR SUPPLY consignee_city: ONTARIO consignee_state: CA notify_party: EXAMPLE OUTDOOR SUPPLY shipper: EXAMPLE FURNITURE CO LTD shipper_country: PEOPLES REP OF CHINA commodity_short_description: OFFICE CHAIRS commodity_hs_code_6: '940130' commodity_hs_code_6_description: Swivel seats with variable height adjustment commodity_quantity: 420 commodity_quantity_uom: CTN commodity_estimated_value: 38000 bol_metric_tons: 8.2 bol_teus: 2 nvocc_scac: null nvocc_scac_description: null commodities_truncated: false note: >- only the most recent US import of this container is on record; earlier imports are not included '400': $ref: '#/components/responses/TradeIntelBadRequest' '401': $ref: '#/components/responses/TradeIntelUnauthorized' '403': $ref: '#/components/responses/TradeIntelNotEnabled' '422': $ref: '#/components/responses/TradeIntelValidationFailed' '429': $ref: '#/components/responses/TradeIntelRateLimited' '502': $ref: '#/components/responses/TradeIntelUnavailable' '504': $ref: '#/components/responses/TradeIntelUnavailable' components: schemas: TradeIntelContainerLookupRequest: type: object properties: container_number: type: string description: >- ISO 6346 container number. Spaces and hyphens are removed and letters uppercased before matching. minLength: 1 maxLength: 20 example: MSCU1234567 required: - container_number TradeIntelContainerLookup: type: object properties: container_number: type: string description: The normalized container number that was looked up. example: MSCU1234567 found: type: boolean description: >- `false` when no US import of this container is on record, or the number is malformed. error: type: string description: Only when `found` is `false` because the number is malformed. example: expected ISO 6346 format, e.g. MSCU1234567 latest_import: type: object description: >- Summary of the container's most recent US import (import date, carrier, vessel, ports, and destination), present when `found` is `true`. properties: {} additionalProperties: true bills_of_lading: type: array items: $ref: '#/components/schemas/TradeIntelContainerBillOfLading' description: Bills of lading the container travelled under on that import. commodities: type: array items: $ref: '#/components/schemas/TradeIntelCommodityLine' description: >- Commodity lines on those bills, grouped by bill with the highest estimated value first within each bill. At most 200 lines are returned; the cap keeps the first 200 in that order, not the 200 highest-value lines overall. commodities_truncated: type: boolean description: >- `true` when more than 200 commodity lines exist and only the first 200 are returned. note: type: string description: Coverage caveat for this response. example: >- only the most recent US import of this container is on record; earlier imports are not included required: - container_number - found TradeIntelContainerBillOfLading: type: object description: >- A bill of lading the container travelled under on its most recent US import. properties: imported_on: type: string description: Import date. format: date nullable: true master_bill_of_lading_number: type: string description: Carrier (master) bill of lading number. nullable: true house_bill_of_lading_number: type: string description: House bill of lading number, when the cargo moved under an NVOCC. nullable: true scac: type: string description: Ocean carrier SCAC. nullable: true scac_name: type: string description: Ocean carrier name. nullable: true vessel_name: type: string nullable: true voyage_number: type: string nullable: true port_of_lading_name: type: string description: Foreign port where the container was loaded. nullable: true port_of_lading_country: type: string nullable: true port_of_discharge_name: type: string description: US port where the container was discharged. nullable: true destination_city: type: string nullable: true destination_state: type: string description: Two-letter US state. nullable: true ultimate_origin_country: type: string nullable: true container_type_short_description: type: string description: Container type, for example a 40-foot high cube. nullable: true container_teu: type: number description: TEUs of the container. nullable: true container_reefer_flag: type: boolean description: Whether the container is refrigerated. nullable: true TradeIntelCommodityLine: type: object description: One commodity line from a bill of lading, with the parties on that bill. properties: imported_on: type: string description: Import date. format: date nullable: true master_bill_of_lading_number: type: string description: Carrier (master) bill of lading number. nullable: true house_bill_of_lading_number: type: string description: House bill of lading number, when the cargo moved under an NVOCC. nullable: true consignee: type: string description: Consignee name as declared on the manifest. nullable: true consignee_city: type: string nullable: true consignee_state: type: string description: Two-letter US state. nullable: true notify_party: type: string description: Notify party as declared on the manifest. nullable: true shipper: type: string description: Shipper name as declared on the manifest. nullable: true shipper_country: type: string nullable: true commodity_short_description: type: string description: Goods description from the manifest line. nullable: true commodity_hs_code_6: type: string description: 6-digit HS code assigned to the line. nullable: true commodity_hs_code_6_description: type: string nullable: true commodity_quantity: type: number description: Declared quantity. nullable: true commodity_quantity_uom: type: string description: Unit of the declared quantity. nullable: true commodity_estimated_value: type: number description: Modelled USD estimate for the line, not declared customs value. nullable: true bol_metric_tons: type: number description: Weight of the bill of lading in metric tons. nullable: true bol_teus: type: number description: TEUs on the bill of lading. nullable: true nvocc_scac: type: string description: SCAC of the NVOCC, when one filed the bill. nullable: true nvocc_scac_description: type: string description: NVOCC name. nullable: true TradeIntelError: type: object description: >- Plain JSON error body returned by trade intelligence endpoints (not JSON:API). properties: error: type: string description: >- What was wrong with the request, or why trade intelligence could not answer. example: >- hs4 must be a 4-digit HS code, e.g. '0306'; use commodities/search to find one required: - error TradeIntelValidationError: type: object description: >- Schema validation failure (for example a `limit` above its maximum or a malformed month). properties: detail: type: array items: type: object properties: loc: type: array items: oneOf: - type: string - type: integer description: Path to the offending field, for example `["body", "limit"]`. msg: type: string description: Human-readable validation message. type: type: string description: Validation error type, for example `less_than_equal`. required: - loc - msg - type description: One entry per field that failed schema validation. required: - detail responses: TradeIntelBadRequest: description: >- Bad Request - the request was understood but a value is invalid, for example an `hs4` that is not a 4-digit HS code. content: application/json: schema: $ref: '#/components/schemas/TradeIntelError' example: error: >- hs4 must be a 4-digit HS code, e.g. '0306'; use commodities/search to find one TradeIntelUnauthorized: description: Unauthorized - the API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/TradeIntelError' example: error: Terminal49 API key could not be verified TradeIntelNotEnabled: description: >- Forbidden - trade intelligence is not enabled for this account. Contact sales@terminal49.com. content: application/json: schema: $ref: '#/components/schemas/TradeIntelError' example: error: Trade intelligence is not enabled for this account TradeIntelValidationFailed: description: >- Unprocessable Entity - the body failed schema validation (a value out of range, a malformed month, or an unknown enum value). content: application/json: schema: $ref: '#/components/schemas/TradeIntelValidationError' example: detail: - loc: - body - limit msg: Input should be less than or equal to 50 type: less_than_equal TradeIntelRateLimited: description: >- Too Many Requests - about 120 requests per minute are allowed per account. content: application/json: schema: $ref: '#/components/schemas/TradeIntelError' example: error: Rate limit exceeded; retry in a minute TradeIntelUnavailable: description: >- Bad Gateway or Gateway Timeout - trade intelligence is temporarily unavailable; retry shortly. content: application/json: schema: $ref: '#/components/schemas/TradeIntelError' example: error: Trade intelligence is temporarily unavailable; try again shortly securitySchemes: authorization: name: Authorization type: apiKey in: header description: >- Use a Terminal49 API key in the `Authorization` header with the `Token` prefix. `Authorization: Token YOUR_API_KEY` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.