Altsets
DemoPricingLoginSign up

Sample data and API documentation

Public documentation for the Altsets relationship data API.

Sample Data

Micron Technology→NVIDIA

Supplier MUCustomer NVDA

Supplier revenue
17.62%
Relationship size
9.8B USD
Customer COGS
14.00%
ASML→Micron Technology

Supplier ASMLCustomer MU

Supplier revenue
7.64%
Relationship size
3B USD
Customer COGS
11.91%
Shin-Etsu Chemical→Micron Technology

Supplier 4063Customer MU

Supplier revenue
1.83%
Relationship size
59.1B JPY
Customer COGS
1.34%
LG Energy Solution→Tesla

Supplier 373220Customer TSLA

Supplier revenue
19.03%
Relationship size
4.7T KRW
Customer COGS
3.41%

Documentation

Account-specific credit balances are private, so this public copy uses placeholders for credit values.

On this page

Authentication

Send your API key using either an Authorization bearer header or an x-api-key header.

Authorization: Bearer alt_live_your_key_here

x-api-key: alt_live_your_key_here

Credits

Relationships and metrics consume credits when they are first unlocked. Already-unlocked data does not consume credits again. Per-request limits are safety limits, not monthly entitlements.

Relationship reveal1 credit
Relationship size5 credits
Supplier revenue percentage5 credits
Customer cost percentage5 credits

A newly revealed relationship containing all three metrics can cost up to 16 credits: 1 for the relationship and 15 for its metrics.

Credits remainingAccount balance
Credits grantedPlan allowance

Search entities

Search for a company or ticker first, then use the returned entity key in relationship requests.

curl "https://www.altsets.com/api/v1/entities/search?q=amazon&limit=5" \
  -H "Authorization: Bearer alt_live_your_key_here"

{
  "data": [
    {
      "entityKey": "AMAZON COM INC",
      "entityId": "ent_1a2b3c4d5e6f7890abcd",
      "symbol": "AMZN",
      "name": "Amazon.com Inc",
      "country": "US",
      "type": null,
      "match": {
        "alias": "amazon",
        "aliasType": null,
        "score": 1
      }
    }
  ],
  "meta": {
    "status": "ok",
    "query": "amazon",
    "count": 1
  }
}

Read unlocked relationships

GET requests are read-only. They return relationships and metrics the account has already unlocked and do not spend credits. Omit date for the latest available data, or provide a valid YYYY-MM-DD date for an allowed point-in-time request.

Requested limits may be reduced by plan and safety limits, so a response may contain fewer rows than the requested limit.

curl "https://www.altsets.com/api/v1/relationships?entityKey=AMAZON%20COM%20INC&direction=customers&limit=50" \
  -H "Authorization: Bearer alt_live_your_key_here"

curl "https://www.altsets.com/api/v1/relationships?entityKey=AMAZON%20COM%20INC&direction=customers&date=2012-05-01&limit=50" \
  -H "Authorization: Bearer alt_live_your_key_here"

Unlock relationships and metrics

Use one POST request to select and unlock relationship rows together with their available metrics. Metric-backed relationships are prioritized first, and no-metric relationships fill any remaining positions in the effective request limit.

If the metrics field is omitted from a POST request, all three metrics are requested by default: relationship size, supplier revenue percentage, and customer cost percentage. Specify metrics explicitly when you only want a subset.

confirmSpend must be true. The idempotency key prevents the same spending request from being submitted twice. Reuse the same key only when replaying the exact same request, and use a new unique key for each distinct unlock request.

curl -X POST "https://www.altsets.com/api/v1/relationships" \
  -H "Authorization: Bearer alt_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: amazon-customers-current-001" \
  -d '{
    "entityKey": "AMAZON COM INC",
    "direction": "customers",
    "limit": 50,
    "metrics": [
      "relationshipSize",
      "supplierRevenuePercent",
      "customerCostPercent"
    ],
    "confirmSpend": true
  }'

curl -X POST "https://www.altsets.com/api/v1/relationships" \
  -H "Authorization: Bearer alt_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: amazon-customers-2012-05-01-001" \
  -d '{
    "entityKey": "AMAZON COM INC",
    "direction": "customers",
    "date": "2012-05-01",
    "limit": 50,
    "metrics": [
      "relationshipSize",
      "supplierRevenuePercent",
      "customerCostPercent"
    ],
    "confirmSpend": true
  }'
Available metrics only

A metric is only submitted for unlock when that relationship has a value for it. Relationships without metrics remain valid relationship results.

Partial success

Business-level partial results still return HTTP 200. Successfully completed unlocks remain available. Inspect the credits object and optional errors array to determine what succeeded and what failed.

Response shape

Relationship-size values are returned in full owner-currency units, not millions. Currency may be null when no exact owner-currency mapping is available.

{
  "date": "2012-05-01",
  "data": [
    {
      "relationshipId": "AMAZON COM INC|SAGE GROUP PLC|customer",
      "supplier": {
        "entityKey": "AMAZON COM INC",
        "symbol": "AMZN",
        "name": "Amazon.com Inc",
        "country": "US"
      },
      "customer": {
        "entityKey": "SAGE GROUP PLC",
        "symbol": "SGE",
        "name": "Sage Group PLC",
        "country": "GB"
      },
      "metrics": {
        "relationshipSize": {
          "value": 125000000,
          "currency": "USD"
        },
        "supplierRevenuePercent": {
          "value": 3.4
        }
      }
    },
    {
      "relationshipId": "AMAZON COM INC|EXAMPLE CUSTOMER|customer",
      "supplier": {
        "entityKey": "AMAZON COM INC",
        "symbol": "AMZN",
        "name": "Amazon.com Inc",
        "country": "US"
      },
      "customer": {
        "entityKey": "EXAMPLE CUSTOMER",
        "symbol": null,
        "name": "Example Customer",
        "country": null
      }
    }
  ],
  "credits": {
    "charged": 12,
    "remaining": 488
  }
}

Historical metric values

The relationship query returns the metric value for the requested latest or historical date. The separate values endpoint resolves the relationship using the supplier and customer entity keys returned by a relationship row.

curl "https://www.altsets.com/api/v1/relationship-values?entityKey=AMAZON%20COM%20INC&direction=customers&relationshipDate=2012-05-01&supplierEntityKey=AMAZON%20COM%20INC&customerEntityKey=SAGE%20GROUP%20PLC&metric=supplierRevenuePercent&dates=2012-05-01" \
  -H "Authorization: Bearer alt_live_your_key_here"

{
  "supplier": {
    "entityKey": "AMAZON COM INC",
    "name": "Amazon.com Inc"
  },
  "customer": {
    "entityKey": "SAGE GROUP PLC",
    "name": "Sage Group PLC"
  },
  "metric": "supplierRevenuePercent",
  "data": [
    {
      "date": "2012-05-01",
      "value": 3.4
    }
  ]
}

Minimal JavaScript example

This Node.js example searches for an entity, unlocks up to ten customer relationships with all available metrics, and prints the resulting rows.

const apiKey = process.env.ALTSETS_API_KEY;
const baseUrl = "https://www.altsets.com";

async function altsets(path, options = {}) {
  const response = await fetch(baseUrl + path, {
    ...options,
    headers: {
      Authorization: `Bearer ${apiKey}`,
      ...(options.headers ?? {})
    }
  });

  const body = await response.json();

  if (!response.ok) {
    throw new Error(
      `${response.status} ${body.error?.code ?? response.statusText}: ${body.error?.message ?? "Request failed"}`
    );
  }

  return body;
}

const search = await altsets(
  "/api/v1/entities/search?q=amazon&limit=1"
);

const entityKey = search.data[0]?.entityKey;

if (!entityKey) {
  throw new Error("No matching entity found.");
}

const result = await altsets(
  "/api/v1/relationships",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Idempotency-Key":
        `amazon-customers-${crypto.randomUUID()}`
    },
    body: JSON.stringify({
      entityKey,
      direction: "customers",
      limit: 10,
      metrics: [
        "relationshipSize",
        "supplierRevenuePercent",
        "customerCostPercent"
      ],
      confirmSpend: true
    })
  }
);

console.log(result.data);
console.log(result.credits);

Common request errors

Error responses include an error code that can be handled programmatically. Common spending and history errors include:

unlock_confirmation_required
missing_idempotency_key
invalid_idempotency_key
idempotency_key_reused
idempotency_request_in_progress
historical_access_not_enabled
historical_period_not_available_for_plan