Shard Access (Signed URLs)

Return signed URLs for binder and non-binder Parquet shards so you can rank compounds, train models, and support target decisions with binding and selectivity scores. Access requires qualifying Data Generation output for the requested `protein_uuid`.

POST/v2/data-access/shards

Shard Access (Signed URLs)

Return signed URLs for existing Parquet shards. Use the Om SDK or your analytics workflow to load, filter, and analyze shard data.

cURL
curl -X POST https://api.omtx.ai/v2/data-access/shards \
  -H "x-api-key: YOUR_API_KEY" \
  -H "idempotency-key: export-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
    "protein_uuid": "YOUR_GENERATED_PROTEIN_UUID"
  }'
Response
{
  "protein_uuid": "YOUR_GENERATED_PROTEIN_UUID",
  "dataset_id": "dataset-generated-v2",
  "vintage_id": "2b8a7a1b-6f38-4c8e-9e1d-0d4e6e8f9a12",
  "vintage": "20260201_om1",
  "binders": {
    "urls": [
      {
        "file_path": "part-00000.parquet",
        "url": "SECURE SIGNED URL"
      }
    ]
  },
  "non_binders": {
    "urls": [
      {
        "file_path": "part-00000.parquet",
        "url": "SECURE SIGNED URL"
      }
    ]
  },
  "binder_urls": [
    "SECURE SIGNED URL"
  ],
  "non_binder_urls": [
    "SECURE SIGNED URL"
  ],
  "expires_at": "2026-02-01T00:00:00Z"
}
  • Generated Data versions require qualifying Data Generation output for the requested protein UUID.
  • The API returns the newest Generated Data version available to your account for the requested protein_uuid.
  • dataset_id, vintage, and vintage_id are returned as provenance metadata for the resolved data version; do not send them in the request.
  • Examples below use a Generated Data protein UUID from /v2/datasets/catalog.
  • Access follows your qualifying Data Generation output.
  • Returns signed URLs for the full shard set in that Generated Data export.
  • Primary SDK path: client.load_data(...) loads binders and non-binders together in one call.
  • For explicit per-pool control, use client.load_binders(...) and client.load_nonbinders(...).
  • Use binding_score and selectivity_score to rank compounds and prioritize candidates.
  • The API returns all shard URLs; your SDK decides how many rows to load into modeling workflows.
  • If n is omitted (or n=None) in SDK loaders, the full pool is loaded.
  • client.binders.urls(...) returns flat binder_urls / non_binder_urls lists for direct URL handling.
  • Signed URLs expire after 60 minutes. Request fresh URLs when needed for long-running jobs.
  • Idempotency-Key header is required for POST requests.
  • Generated Data outputs can be reused in Hub workflows and paired with Diligence target research.

Request Parameters

  • protein_uuid (required): Target protein UUID.

Python SDK

Combined training load (recommended)Python
from omtx import OmClient

client = OmClient(api_key="YOUR_API_KEY")

loaded = client.load_data(
    protein_uuid="YOUR_GENERATED_PROTEIN_UUID",
    binders=50000,
    nonbinder_multiplier=5,
    sample_seed=42,
)
binders = loaded["binders"]
nonbinders = loaded["nonbinders"]

print("Loaded shapes:", binders.shape, nonbinders.shape)
binders.show(top_n=24)  # defaults: smiles + binding_score
Load binder and non-binder pools directly (recommended)Python
from omtx import OmClient

client = OmClient(api_key="YOUR_API_KEY")

binders = client.load_binders(
    protein_uuid="YOUR_GENERATED_PROTEIN_UUID",
    n=1000,
    sample_seed=42,
)
nonbinders = client.load_nonbinders(
    protein_uuid="YOUR_GENERATED_PROTEIN_UUID",
    n=10000,
    sample_seed=42,
)
# Omit n (or set n=None) to load the full pool.

print("Loaded shapes:", binders.shape, nonbinders.shape)
binders.show(top_n=24)  # defaults: smiles + binding_score
Advanced: request signed URL listsPython
from omtx import OmClient

client = OmClient(api_key="YOUR_API_KEY")

urls = client.binders.urls(
    protein_uuid="YOUR_GENERATED_PROTEIN_UUID",
)

print("Binder shards:", len(urls["binder_urls"]))
print("First binder URL:", urls["binder_urls"][0])

Parquet Columns

  • smiles
  • gene
  • uniprot_id
  • sequence
  • MW
  • logP
  • PSA
  • HBD
  • HBA
  • binding_score
  • selectivity_score