Get Components

GET /api/partner/projects/{project_id}/components

Requires the access described in Partner API Overview. This is a parsed view of a stored schematic, not an ERC result, PCB connectivity export or complete managed-project API.

Parameters

project_idstringpathrequired

The authorized Trace conversation ID associated with stored schematic versions. Do not use a managed-project UUID, branch ID or share-link token.

include_rawbooleanquerydefault: true

Include the source .trace_sch text as raw. Set to false when it is not needed.

include_datasheetsbooleanquerydefault: false

Include per-component datasheet status and available parsed datasheet data. Lookup or refresh work may be scheduled; this does not edit CAD.

Response

project_idstring

Echo of the conversation ID supplied in the path.

formatstring

"trace_sch".

version_numberinteger

Sequence number of the parsed stored schematic version.

componentsarray

Parsed component entries sorted by reference. Fields are ref, symbol, value, footprint, mpn, manufacturer, datasheet, uid, unit and pins. pins maps pin-number strings to net-name strings. Missing property fields can be null; a UID or property is not independently verified identity. Keep multi-unit entries distinct.

netlistobject

A net-keyed map of sorted ref.pin endpoints from the parsed pin assignments. Empty/unassigned nets are not added as connectivity keys.

declared_netsarray

Sorted explicitly declared net names. Implicit pin assignments can make this a subset of the netlist keys.

rawstring

Source .trace_sch text, present only when include_raw=true.

The view reports what the stored schematic declares. Do not interpret it as proof of every hierarchical connection, physical PCB route or fitted component.

Example

Supply partner_token through your application's secret configuration. The conversation ID comes from authorized session context.

from urllib.parse import quote

import requests


def get_components(conversation_id: str, partner_token: str) -> dict:
    identifier = quote(conversation_id, safe="")
    response = requests.get(
        f"https://api.buildwithtrace.com/api/partner/projects/{identifier}/components",
        headers={"Authorization": f"Bearer {partner_token}"},
        params={"include_raw": "false", "include_datasheets": "false"},
        timeout=(10, 30),
    )
    response.raise_for_status()
    return response.json()

An illustrative response for the resistor snapshot in Get Schematic:

{
  "project_id": "11111111-1111-4111-8111-111111111111",
  "format": "trace_sch",
  "version_number": 7,
  "components": [
    {
      "ref": "R1",
      "symbol": "Device:R",
      "value": "10k",
      "footprint": null,
      "mpn": null,
      "manufacturer": null,
      "datasheet": null,
      "uid": "22222222-2222-4222-8222-222222222222",
      "unit": 1,
      "pins": {"1": "VCC", "2": "SIG"}
    }
  ],
  "netlist": {"SIG": ["R1.2"], "VCC": ["R1.1"]},
  "declared_nets": []
}

No raw field is present because the example requests include_raw=false.

Datasheet IR semantics

With include_datasheets=true, entries additionally include datasheet_status and datasheet_ir:

cached: cached parsed datasheet data is returned.
refreshing: existing data is returned while refresh work is scheduled. Do not assume the returned data is freshly verified.
pending: no cached data is available; lookup/parse work may be scheduled. datasheet_ir is null.
no_mpn: no manufacturer part number is available for lookup; datasheet_ir is null.

The datasheet_ir value is an object or null. Review its actual content and source; a status does not certify the package, pinout or operating conditions. Pending work has no guaranteed completion time. Use bounded polling/backoff and retain a visible unavailable state rather than assuming the next read must be cached.

Errors and freshness

Handle the overview's failures. This endpoint can return 422 for stored schematic parsing failure and 503 when parsing is unavailable; these are not empty component lists.

The latest version can change between calls. Compare version_number when combining reads; these routes do not accept a revision-pinning parameter. Neither stored connectivity nor datasheet metadata authorizes a physical hardware action.