curl --request POST \
--url "https://api.rafflesia.ai/v1/homology/batch" \
--header "Authorization: Bearer $RAFFLESIA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"queries": [
{
"kind": "protein_sequence",
"sequence": "<sequence>"
}
]
}'
{
"object": "homology_search_result_set_batch",
"performance": {
"is_cache_hit": true,
"queue_wait_ms": 1,
"search_execution_ms": 1,
"server_total_ms": 1
},
"request_id": "<string>",
"responses": [
{
"candidates": [
{
"measurements": {
"affine": {
"normalized_score": 123,
"raw_score": 123
},
"late_interaction": {
"distance": 123,
"mean_closest_cosine_distance": 123,
"mean_closest_cosine_similarity": 123,
"query_token_count": 123
},
"maxsim": {
"bidirectional": 123,
"query_to_target": 123,
"target_to_query": 123
}
},
"rank": 2,
"target": {
"id": "<string>",
"sequence": "<string>",
"attributes": {}
},
"alignment": {
"aligned_residue_count": 1,
"cigar": "<string>",
"cigar_dialect": "extended",
"coordinate_system": "zero_based_half_open",
"gap_opening_count": 1,
"gap_residue_count": 1,
"identical_residue_count": 1,
"query_coverage_ratio": 0.5,
"query_end": 1,
"query_length": 2,
"query_start": 1,
"sequence_identity_ratio": 0.5,
"target_coverage_ratio": 0.5,
"target_end": 1,
"target_length": 2,
"target_start": 1
},
"significance": {
"status": "supported_empirical",
"measurements": {
"calibration_id": "<string>",
"calibration_sample_count": 1,
"is_family_wise_lower_bound": true,
"searched_residue_count": 1,
"searched_sequence_count": 1,
"support_status": "supported_empirical",
"bit_score": 123,
"calibration_bin": "<string>",
"e_value_calibration_id": "<string>",
"e_value_conditioning_context_id": "<string>",
"e_value_estimand": "<string>",
"e_value_maximum_log_extrapolation_factor": 1,
"e_value_method": "<string>",
"e_value_null_population_id": "<string>",
"e_value_qualification_id": "<string>",
"e_value_search_policy_id": "<string>",
"e_value_searched_inventory_id": "<string>",
"e_value_supported_log_maximum": 123,
"e_value_supported_log_minimum": 123,
"e_value_tail_coordinate": 123,
"e_value_target_stratum_count": 1,
"expected_false_hits": 1,
"family_wise_exceedance_probability": 0.5,
"is_e_value_upper_bound": true,
"log_expected_false_hits": 123,
"minimum_resolvable_probability": 0.5,
"pair_tail_log_probability": 123,
"pair_tail_probability": 0.5,
"pair_tail_surprisal_bits": 1,
"q_value": 0.5,
"tail_model": {
"fit_exceedance_count": 1,
"holdout_exceedance_count": 1,
"holdout_kolmogorov_smirnov": 0.5,
"holdout_significance_level": 0.5,
"k": 1,
"lambda": 1,
"threshold_score": 123
}
},
"reason": "<string>"
}
}
],
"database": {
"corpus_snapshot_id": "<string>",
"id": "<string>",
"release_id": "<string>",
"searched_residue_count": 1,
"searched_target_count": 1,
"slug": "<string>",
"canonical_filter_sha256": "<string>",
"target_space_id": "<string>"
},
"evidence_summary": {
"alignment": {
"affected_candidate_count": 1,
"candidate_count": 1,
"status": "not_requested",
"reason": "<string>"
},
"is_requested_evidence_complete": true,
"requested": "candidate_measurement",
"significance": {
"affected_candidate_count": 1,
"candidate_count": 1,
"requirement": "not_requested",
"status": "not_requested",
"reason": "no_qualified_calibration"
}
},
"execution": {
"created_at": "2023-11-07T05:31:56Z",
"engine": "<string>",
"policy": {
"is_deterministic": true,
"is_exhaustive": true,
"is_fallback": true,
"outcome": "complete_exact",
"requested_guarantee": "approximate",
"resolution_reason": "<string>",
"resolved_guarantee": "approximate"
},
"semantic_profile_id": "<string>",
"server_version": "<string>",
"engine_release": "<string>"
},
"is_result_limit_reached": true,
"object": "homology_candidate_set",
"query": {
"kind": "protein_sequence",
"normalization_id": "<string>",
"normalized_length": 50000,
"sha256": "<string>"
},
"query_index": 1,
"ranking": {
"comparability": "within_query_only",
"order": "ascending",
"primary_measurement": "maxsim.bidirectional",
"scope": "resolved_policy_frontier",
"tie_breakers": [
{
"field": "maxsim.bidirectional",
"order": "ascending"
}
]
},
"receipt": {
"bytes": 2,
"id": "<string>",
"sha256": "<string>"
},
"result_sha256": "<string>",
"usage": {
"logical_bytes_returned": 1,
"billable_formula_id": "<string>",
"billable_units": 1,
"logical_bytes_read": 1
},
"warnings": [
{
"code": "<string>",
"message": "<string>",
"details": {}
}
]
}
],
"result_sha256": "<string>",
"usage": {
"logical_bytes_returned": 1,
"billable_formula_id": "<string>",
"billable_units": 1,
"logical_bytes_read": 1
},
"warnings": [
{
"code": "<string>",
"message": "<string>",
"details": {}
}
]
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}Runs 1 to 16 ordered typed protein queries with shared search controls. The operation is bounded, synchronous, and all-or-nothing: it returns completed candidate sets in query order or one error for the complete batch.
curl --request POST \
--url "https://api.rafflesia.ai/v1/homology/batch" \
--header "Authorization: Bearer $RAFFLESIA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"queries": [
{
"kind": "protein_sequence",
"sequence": "<sequence>"
}
]
}'
{
"object": "homology_search_result_set_batch",
"performance": {
"is_cache_hit": true,
"queue_wait_ms": 1,
"search_execution_ms": 1,
"server_total_ms": 1
},
"request_id": "<string>",
"responses": [
{
"candidates": [
{
"measurements": {
"affine": {
"normalized_score": 123,
"raw_score": 123
},
"late_interaction": {
"distance": 123,
"mean_closest_cosine_distance": 123,
"mean_closest_cosine_similarity": 123,
"query_token_count": 123
},
"maxsim": {
"bidirectional": 123,
"query_to_target": 123,
"target_to_query": 123
}
},
"rank": 2,
"target": {
"id": "<string>",
"sequence": "<string>",
"attributes": {}
},
"alignment": {
"aligned_residue_count": 1,
"cigar": "<string>",
"cigar_dialect": "extended",
"coordinate_system": "zero_based_half_open",
"gap_opening_count": 1,
"gap_residue_count": 1,
"identical_residue_count": 1,
"query_coverage_ratio": 0.5,
"query_end": 1,
"query_length": 2,
"query_start": 1,
"sequence_identity_ratio": 0.5,
"target_coverage_ratio": 0.5,
"target_end": 1,
"target_length": 2,
"target_start": 1
},
"significance": {
"status": "supported_empirical",
"measurements": {
"calibration_id": "<string>",
"calibration_sample_count": 1,
"is_family_wise_lower_bound": true,
"searched_residue_count": 1,
"searched_sequence_count": 1,
"support_status": "supported_empirical",
"bit_score": 123,
"calibration_bin": "<string>",
"e_value_calibration_id": "<string>",
"e_value_conditioning_context_id": "<string>",
"e_value_estimand": "<string>",
"e_value_maximum_log_extrapolation_factor": 1,
"e_value_method": "<string>",
"e_value_null_population_id": "<string>",
"e_value_qualification_id": "<string>",
"e_value_search_policy_id": "<string>",
"e_value_searched_inventory_id": "<string>",
"e_value_supported_log_maximum": 123,
"e_value_supported_log_minimum": 123,
"e_value_tail_coordinate": 123,
"e_value_target_stratum_count": 1,
"expected_false_hits": 1,
"family_wise_exceedance_probability": 0.5,
"is_e_value_upper_bound": true,
"log_expected_false_hits": 123,
"minimum_resolvable_probability": 0.5,
"pair_tail_log_probability": 123,
"pair_tail_probability": 0.5,
"pair_tail_surprisal_bits": 1,
"q_value": 0.5,
"tail_model": {
"fit_exceedance_count": 1,
"holdout_exceedance_count": 1,
"holdout_kolmogorov_smirnov": 0.5,
"holdout_significance_level": 0.5,
"k": 1,
"lambda": 1,
"threshold_score": 123
}
},
"reason": "<string>"
}
}
],
"database": {
"corpus_snapshot_id": "<string>",
"id": "<string>",
"release_id": "<string>",
"searched_residue_count": 1,
"searched_target_count": 1,
"slug": "<string>",
"canonical_filter_sha256": "<string>",
"target_space_id": "<string>"
},
"evidence_summary": {
"alignment": {
"affected_candidate_count": 1,
"candidate_count": 1,
"status": "not_requested",
"reason": "<string>"
},
"is_requested_evidence_complete": true,
"requested": "candidate_measurement",
"significance": {
"affected_candidate_count": 1,
"candidate_count": 1,
"requirement": "not_requested",
"status": "not_requested",
"reason": "no_qualified_calibration"
}
},
"execution": {
"created_at": "2023-11-07T05:31:56Z",
"engine": "<string>",
"policy": {
"is_deterministic": true,
"is_exhaustive": true,
"is_fallback": true,
"outcome": "complete_exact",
"requested_guarantee": "approximate",
"resolution_reason": "<string>",
"resolved_guarantee": "approximate"
},
"semantic_profile_id": "<string>",
"server_version": "<string>",
"engine_release": "<string>"
},
"is_result_limit_reached": true,
"object": "homology_candidate_set",
"query": {
"kind": "protein_sequence",
"normalization_id": "<string>",
"normalized_length": 50000,
"sha256": "<string>"
},
"query_index": 1,
"ranking": {
"comparability": "within_query_only",
"order": "ascending",
"primary_measurement": "maxsim.bidirectional",
"scope": "resolved_policy_frontier",
"tie_breakers": [
{
"field": "maxsim.bidirectional",
"order": "ascending"
}
]
},
"receipt": {
"bytes": 2,
"id": "<string>",
"sha256": "<string>"
},
"result_sha256": "<string>",
"usage": {
"logical_bytes_returned": 1,
"billable_formula_id": "<string>",
"billable_units": 1,
"logical_bytes_read": 1
},
"warnings": [
{
"code": "<string>",
"message": "<string>",
"details": {}
}
]
}
],
"result_sha256": "<string>",
"usage": {
"logical_bytes_returned": 1,
"billable_formula_id": "<string>",
"billable_units": 1,
"logical_bytes_read": 1
},
"warnings": [
{
"code": "<string>",
"message": "<string>",
"details": {}
}
]
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}{
"error": {
"code": "<string>",
"doc_url": "<string>",
"message": "<string>",
"request_id": "<string>",
"type": "invalid_request_error",
"details": {},
"param": "<string>"
}
}Authorizations
A Rafflesia API key, sent as Authorization: Bearer <key>.
Headers
Optional retry identity retained for 24 hours for the complete all-or-nothing batch. Reuse the same key only with the same request. When omitted, each item in each HTTP request is a distinct billable operation.
255Optional dated contract pin. Omit to use the current 2026-08-08 homology contract; any other value returns api_version_unsupported.
Body
An ordered batch of 1 to 16 typed biological queries sharing every search control.
1 - 16 elementsShow child attributes
Show child attributes
Database id or slug from homology.databases.list. Omit both database selectors to use the server-advertised default database and its default release. Mutually exclusive with database_release_id.
1 - 256Exact immutable dbr_ release id returned by the catalog. Omit both database selectors to use the server-advertised default database and its default release. Mutually exclusive with database.
^dbr_[0-9a-f]{64}$candidate_measurement, pairwise_sequence_alignment Optional exact metadata predicate applied before the release-owned search policy.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
- Option 10
- Option 11
- Option 12
- Option 13
- Option 14
- Option 15
- Option 16
- Option 17
- Option 18
- Option 19
- Option 20
- Option 21
Show child attributes
Show child attributes
approximate, exhaustive Maximum ranked results returned inline for each query, additionally bounded by the selected immutable release. The aggregate may not exceed 10,000 candidate measurements or 1,000 pairwise alignments, and the encoded batch may not exceed 16 MiB.
1 <= x <= 5000not_requested, if_available, required Immutable reusable target space returned as database.target_space_id by a prior filtered homology search and shared by every query. Mutually exclusive with database, database_release_id, and filter.
^htsp_[0-9a-f]{64}$Response
OK
Always homology_search_result_set_batch.
homology_search_result_set_batch Show child attributes
Show child attributes
1 - 16 elementsShow child attributes
Show child attributes
Show child attributes
Show child attributes
Non-fatal warnings. Always an array.
Show child attributes
Show child attributes