> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve a datapoint
> Retrieves a datapoint object
**Related guide**: Datasets guide. See the [Datasets guide](/ai-studio/optimize/datasets) for a walkthrough with examples.
## OpenAPI
````yaml get /v2/datasets/{dataset_id}/datapoints/{datapoint_id}
openapi: 3.1.0
info:
title: orq.ai API
version: '2.0'
description: orq.ai API documentation
servers:
- url: https://my.orq.ai
security:
- ApiKey: []
tags:
- name: Chunking
description: Split text into smaller chunks for retrieval and generation workflows.
- name: File Systems
description: >-
Create and manage persistent file systems that agents and MCP clients read
from and write to.
- name: Knowledge Bases
description: Create and manage knowledge bases used by agents and retrieval workflows.
- name: Memory Stores
description: Create and manage memory stores, memories, and memory documents.
- name: Evals
description: Run an evaluator against a conversation and its result
- name: Logs
description: >-
OpenTelemetry log query API. Search, filter, aggregate, and facet log
records ingested via OTLP.
- name: Reporting
description: >-
GenAI reporting API over canonical analytics rollups. Accepts a metric
name, time range, grain, group-by, and filters; returns a typed time
series and optional totals.
- name: Traces
description: >-
Query and inspect ingested trace data: search trace summaries, aggregate
metrics, and read individual traces and their spans.
- description: List models available through the AI Router.
name: Models
- name: Policies
- name: Alerts
description: >-
Alerts evaluate a Reporting API metric on a fixed interval and fire
notifications through notifiers when the value breaches a threshold. Each
breach opens a trigger that tracks the incident until the value recovers.
- name: Annotation Queues
description: Annotation queues collect spans for human review.
- name: API keys
description: >-
API keys authenticate programmatic access to the workspace. They expose
opaque tokens, per-domain access grants, and budget and rate-limit
constraints.
- name: Audit Logs
description: Audit logs record workspace entity changes and access-relevant events.
- name: Budgets
description: >-
Budgets govern spend, token usage, and request rate across six scopes:
workspace, project, identity, API key, provider, and model. Every
applicable budget is enforced, and the most restrictive limit applies per
dimension.
- name: Files
description: File upload and retrieval operations.
- name: Guardrail Rules
description: >-
Guardrail Rules conditionally enforce evaluators and plugins for AI
Gateway traffic. Rules may be scoped to a project or the whole workspace.
- name: Hub
description: Hub items are reusable templates available to a workspace.
- name: Identities
description: >-
Identities represent end users from your system for usage and engagement
tracking.
- name: Management keys
description: >-
Management keys are workspace-scoped credentials that authenticate
programmatic access to workspace administration surfaces (API keys,
budgets). Unlike project-scoped API keys, a management key always operates
at the workspace level.
- name: MCP Gateway
description: >-
Register upstream MCP servers, discover and sync their tools, and assemble
gateways that expose a curated tool surface to MCP clients.
- name: Model Catalog
description: >-
Browse the orq.ai model catalog: every model orq offers, across every
provider, with pricing, capabilities and benchmark data. List endpoints
only return models that are not deprecated. This API is public, requires
no authentication, and is rate limited to 120 requests per minute per IP.
Responses carry a 5-minute cache-control max-age.
- name: Notifiers
description: Notifier destinations used to send delivery and workflow notifications.
- name: Projects
description: Projects organize resources within a workspace
- name: Routing Rules
description: >-
Routing Rules conditionally select models and enforce request plugins for
AI Gateway traffic. Rules are evaluated by ascending priority and may be
scoped to a project or the whole workspace.
- name: Threads
description: Threads group related trace invocations and their aggregate usage
- name: Skills
description: >-
Skills are modular instructions you can use to codify processes and
conventions
- name: Smart Routers
description: >-
Create and manage workspace Smart Routers. A Smart Router selects a model
from an eligible pool for each request according to a quality, balanced,
or cost profile.
- name: Webhooks
description: >-
Create and manage webhooks that deliver workspace events to external HTTPS
endpoints.
- name: Workspaces
description: >-
A workspace is the tenant. Create is called from a user session during
onboarding; Get, List, and Update are the public management surface.
- name: Workspace Security
description: >-
Workspace-level domain verification and IP allowlist controls. These
operations are restricted to workspace administrators.
- name: Workspace Settings
description: >-
Workspace-level settings managed with a workspace credential. A workspace
is the tenant, so these settings are a singleton — there is nothing to
create or delete, only read and update.
- name: Responses
- description: Run agents on a cron cadence. Minimum firing interval is 1 hour.
name: Agent Schedules
- name: Embeddings
- name: Telemetry
description: >-
Unified query envelope for traces, metrics, and logs. One request shape,
one filter dialect, and one response shape per source, validated by a
per-source registry.
- description: Beta. Run typed classification questions against a classify model.
name: Classify
- description: Search Gateway with managed credits or BYOK.
name: Web Search
externalDocs:
url: https://docs.orq.ai
description: orq.ai Documentation
paths:
/v2/datasets/{dataset_id}/datapoints/{datapoint_id}:
get:
tags:
- Datasets
summary: Retrieve a datapoint
description: Retrieves a datapoint object
operationId: RetrieveDatapoint
parameters:
- schema:
anyOf:
- type: string
- type: string
format: ulid
pattern: ^[0-9A-HJKMNP-TV-Z]{26}$
readOnly: true
description: The id of the resource
description: The unique identifier of the dataset
required: true
description: The unique identifier of the dataset
name: dataset_id
in: path
- schema:
type: string
description: The unique identifier of the datapoint
required: true
description: The unique identifier of the datapoint
name: datapoint_id
in: path
responses:
'200':
description: Datapoint retrieved.
content:
application/json:
schema:
type: object
properties:
_id:
type: string
description: The unique identifier of the dataset item
workspace_id:
type: string
description: The unique identifier of the workspace it belongs to
inputs:
type: object
additionalProperties: {}
description: >-
The inputs of the dataset. Key value pairs where the key
is the input name and the value is the input value. Nested
objects are not supported.
messages:
type: array
items:
oneOf:
- type: object
properties:
role:
type: string
enum:
- system
description: >-
The role of the messages author, in this case
`system`.
content:
anyOf:
- type: string
description: The contents of the system message.
- type: array
items:
$ref: '#/components/schemas/TextContentPartSchema'
minItems: 1
description: >-
An array of content parts with a defined
type. For system messages, only type `text`
is supported.
description: The contents of the system message.
name:
type: string
description: >-
An optional name for the participant. Provides
the model information to differentiate between
participants of the same role.
required:
- role
- content
title: System message
description: >-
Developer-provided instructions that the model
should follow, regardless of messages sent by the
user.
- type: object
properties:
role:
type: string
enum:
- developer
description: >-
The role of the messages author, in this case
`developer`.
content:
anyOf:
- type: string
description: The contents of the developer message.
- type: array
items:
$ref: '#/components/schemas/TextContentPartSchema'
minItems: 1
description: >-
An array of content parts with a defined
type. For developer messages, only type
`text` is supported.
description: The contents of the developer message.
name:
type: string
description: >-
An optional name for the participant. Provides
the model information to differentiate between
participants of the same role.
required:
- role
- content
title: Developer message
- type: object
properties:
role:
type: string
enum:
- user
description: >-
The role of the messages author, in this case
`user`.
name:
type: string
description: >-
An optional name for the participant. Provides
the model information to differentiate between
participants of the same role.
content:
anyOf:
- type: string
description: The text contents of the message.
- type: array
items:
oneOf:
- $ref: >-
#/components/schemas/TextContentPartSchema
- $ref: >-
#/components/schemas/ImageContentPartSchema
- $ref: >-
#/components/schemas/AudioContentPartSchema
- type: object
properties:
type:
type: string
enum:
- file
description: >-
The type of the content part. Always
`file`.
cache_control:
type: object
properties:
type:
type: string
enum:
- ephemeral
description: >-
Create a cache control breakpoint at
this content block. Accepts only the
value "ephemeral".
ttl:
type: string
enum:
- 5m
- 1h
default: 5m
description: >-
The time-to-live for the cache control
breakpoint. This may be one of the
following values:
- `5m`: 5 minutes
- `1h`: 1 hour
Defaults to `5m`. Only supported by
`Anthropic` Claude models.
required:
- type
file:
$ref: >-
#/components/schemas/FileContentPartSchema
required:
- type
- file
description: >-
An array of content parts with a defined
type. Supported options differ based on the
model being used to generate the response.
Can contain text, image, or audio inputs.
description: The contents of the user message.
required:
- role
- content
title: User message
- type: object
properties:
reasoning_content:
type: string
description: >-
Provider reasoning content that must be replayed
with assistant tool calls when continuing a
reasoning-model conversation.
content:
anyOf:
- type: string
description: The contents of the assistant message.
- type: array
items:
oneOf:
- $ref: >-
#/components/schemas/TextContentPartSchema
- $ref: '#/components/schemas/RefusalPartSchema'
- $ref: '#/components/schemas/ReasoningPartSchema'
- $ref: >-
#/components/schemas/RedactedReasoningPartSchema
discriminator:
propertyName: type
mapping:
text: >-
#/components/schemas/TextContentPartSchema
refusal: '#/components/schemas/RefusalPartSchema'
reasoning: '#/components/schemas/ReasoningPartSchema'
redacted_reasoning: >-
#/components/schemas/RedactedReasoningPartSchema
description: >-
An array of content parts with a defined
type. Can be one or more of type `text`, or
exactly one of type `refusal`.
- type: 'null'
description: >-
The contents of the assistant message. Required
unless `tool_calls` or `function_call` is
specified.
refusal:
type:
- string
- 'null'
description: The refusal message by the assistant.
role:
type: string
enum:
- assistant
description: >-
The role of the messages author, in this case
`assistant`.
name:
type: string
description: >-
An optional name for the participant. Provides
the model information to differentiate between
participants of the same role.
audio:
type:
- object
- 'null'
properties:
id:
type: string
description: >-
Unique identifier for a previous audio
response from the model.
required:
- id
description: >-
Data about a previous audio response from the
model.
tool_calls:
type: array
items:
type: object
properties:
id:
type: string
description: The ID of the tool call.
type:
type: string
enum:
- function
description: >-
The type of the tool. Currently, only
`function` is supported.
function:
type: object
properties:
name:
type: string
description: The name of the function to call.
arguments:
type: string
description: >-
The arguments to call the function with,
as generated by the model in JSON
format. Note that the model does not
always generate valid JSON, and may
hallucinate parameters not defined by
your function schema. Validate the
arguments in your code before calling
your function.
thought_signature:
type: string
description: >-
Encrypted representation of the model
internal reasoning state during function
calling. Required by Gemini 3 models when
continuing a conversation after a tool
call.
required:
- id
- type
- function
description: >-
The tool calls generated by the model, such as
function calls.
required:
- role
title: Assistant message
- type: object
properties:
role:
type: string
enum:
- tool
description: >-
The role of the messages author, in this case
tool.
content:
anyOf:
- type: string
- type: array
items:
oneOf:
- $ref: >-
#/components/schemas/TextContentPartSchema
discriminator:
propertyName: type
mapping:
text: >-
#/components/schemas/TextContentPartSchema
description: The contents of the tool message.
tool_call_id:
type:
- string
- 'null'
description: Tool call that this message is responding to.
cache_control:
type: object
properties:
type:
type: string
enum:
- ephemeral
description: >-
Create a cache control breakpoint at this
content block. Accepts only the value
"ephemeral".
ttl:
type: string
enum:
- 5m
- 1h
default: 5m
description: >-
The time-to-live for the cache control
breakpoint. This may be one of the following
values:
- `5m`: 5 minutes
- `1h`: 1 hour
Defaults to `5m`. Only supported by
`Anthropic` Claude models.
required:
- type
required:
- role
- content
- tool_call_id
title: Tool message
description: A list of messages comprising the conversation so far
expected_output:
type: string
evaluations:
type: array
items:
oneOf:
- type: object
properties:
id:
type: string
description: The unique identifier of the human evaluation
evaluation_type:
type: string
enum:
- human_review
description: The type of evaluation
human_review_id:
type: string
description: >-
The unique identifier of the human review.
Omitted on corrections, which inherit the parent
evaluator output schema.
source:
type: string
enum:
- orq
- external
default: orq
annotator:
type: object
properties:
kind:
type: string
enum:
- llm
- code
- human
- automation
description: >-
The kind of annotator that produced the
evaluation
actor_id:
type: string
description: >-
Who/what produced this annotation.
User/contact id for human, evaluator eval
span id for llm/code, automation rule id for
automation.
required:
- kind
- actor_id
description: >-
The annotator that produced this evaluation.
Optional during the dual-write deprecation
window.
output_schema:
type: string
enum:
- boolean
- number
- categorical
- string
description: >-
The expected shape of the value. Derived from
the human review type, or inherited from the
parent annotation for corrections.
parent_annotation_id:
type: string
description: >-
When present, references the id of the
annotation this entry corrects. Presence of this
field marks the entry as a correction.
explanation:
type: string
description: Optional free-text explanation of the value
reviewed_by_id:
type: string
deprecated: true
description: >-
Deprecated: use annotator.actor_id. The unique
identifier of the user who reviewed the item.
reviewed_at:
type: string
format: date-time
default: '2026-09-15T17:33:16.458Z'
deprecated: true
description: >-
Deprecated. The date and time the item was
reviewed
type:
type: string
enum:
- string
value:
type: string
required:
- id
- evaluation_type
- reviewed_by_id
- type
- value
- type: object
properties:
id:
type: string
description: The unique identifier of the human evaluation
evaluation_type:
type: string
enum:
- human_review
description: The type of evaluation
human_review_id:
type: string
description: >-
The unique identifier of the human review.
Omitted on corrections, which inherit the parent
evaluator output schema.
source:
type: string
enum:
- orq
- external
default: orq
annotator:
type: object
properties:
kind:
type: string
enum:
- llm
- code
- human
- automation
description: >-
The kind of annotator that produced the
evaluation
actor_id:
type: string
description: >-
Who/what produced this annotation.
User/contact id for human, evaluator eval
span id for llm/code, automation rule id for
automation.
required:
- kind
- actor_id
description: >-
The annotator that produced this evaluation.
Optional during the dual-write deprecation
window.
output_schema:
type: string
enum:
- boolean
- number
- categorical
- string
description: >-
The expected shape of the value. Derived from
the human review type, or inherited from the
parent annotation for corrections.
parent_annotation_id:
type: string
description: >-
When present, references the id of the
annotation this entry corrects. Presence of this
field marks the entry as a correction.
explanation:
type: string
description: Optional free-text explanation of the value
reviewed_by_id:
type: string
deprecated: true
description: >-
Deprecated: use annotator.actor_id. The unique
identifier of the user who reviewed the item.
reviewed_at:
type: string
format: date-time
default: '2026-09-15T17:33:16.458Z'
deprecated: true
description: >-
Deprecated. The date and time the item was
reviewed
type:
type: string
enum:
- number
value:
type: number
required:
- id
- evaluation_type
- reviewed_by_id
- type
- value
- type: object
properties:
id:
type: string
description: The unique identifier of the human evaluation
evaluation_type:
type: string
enum:
- human_review
description: The type of evaluation
human_review_id:
type: string
description: >-
The unique identifier of the human review.
Omitted on corrections, which inherit the parent
evaluator output schema.
source:
type: string
enum:
- orq
- external
default: orq
annotator:
type: object
properties:
kind:
type: string
enum:
- llm
- code
- human
- automation
description: >-
The kind of annotator that produced the
evaluation
actor_id:
type: string
description: >-
Who/what produced this annotation.
User/contact id for human, evaluator eval
span id for llm/code, automation rule id for
automation.
required:
- kind
- actor_id
description: >-
The annotator that produced this evaluation.
Optional during the dual-write deprecation
window.
output_schema:
type: string
enum:
- boolean
- number
- categorical
- string
description: >-
The expected shape of the value. Derived from
the human review type, or inherited from the
parent annotation for corrections.
parent_annotation_id:
type: string
description: >-
When present, references the id of the
annotation this entry corrects. Presence of this
field marks the entry as a correction.
explanation:
type: string
description: Optional free-text explanation of the value
reviewed_by_id:
type: string
deprecated: true
description: >-
Deprecated: use annotator.actor_id. The unique
identifier of the user who reviewed the item.
reviewed_at:
type: string
format: date-time
default: '2026-09-15T17:33:16.458Z'
deprecated: true
description: >-
Deprecated. The date and time the item was
reviewed
type:
type: string
enum:
- boolean
value:
type: boolean
required:
- id
- evaluation_type
- reviewed_by_id
- type
- value
- type: object
properties:
id:
type: string
description: The unique identifier of the human evaluation
evaluation_type:
type: string
enum:
- human_review
description: The type of evaluation
human_review_id:
type: string
description: >-
The unique identifier of the human review.
Omitted on corrections, which inherit the parent
evaluator output schema.
source:
type: string
enum:
- orq
- external
default: orq
annotator:
type: object
properties:
kind:
type: string
enum:
- llm
- code
- human
- automation
description: >-
The kind of annotator that produced the
evaluation
actor_id:
type: string
description: >-
Who/what produced this annotation.
User/contact id for human, evaluator eval
span id for llm/code, automation rule id for
automation.
required:
- kind
- actor_id
description: >-
The annotator that produced this evaluation.
Optional during the dual-write deprecation
window.
output_schema:
type: string
enum:
- boolean
- number
- categorical
- string
description: >-
The expected shape of the value. Derived from
the human review type, or inherited from the
parent annotation for corrections.
parent_annotation_id:
type: string
description: >-
When present, references the id of the
annotation this entry corrects. Presence of this
field marks the entry as a correction.
explanation:
type: string
description: Optional free-text explanation of the value
reviewed_by_id:
type: string
deprecated: true
description: >-
Deprecated: use annotator.actor_id. The unique
identifier of the user who reviewed the item.
reviewed_at:
type: string
format: date-time
default: '2026-09-15T17:33:16.459Z'
deprecated: true
description: >-
Deprecated. The date and time the item was
reviewed
type:
type: string
enum:
- string_array
values:
type: array
items:
type: string
required:
- id
- evaluation_type
- reviewed_by_id
- type
- values
description: Evaluations associated with the datapoint
dataset_id:
type: string
description: The unique identifier of the dataset
snapshot_version:
type: string
description: The version of the dataset snapshot
created_by_id:
type:
- string
- 'null'
description: The unique identifier of the user who created the dataset
updated_by_id:
type:
- string
- 'null'
description: >-
The unique identifier of the user who last updated the
dataset
created:
anyOf:
- type: string
format: date-time
- type: string
format: date-time
default: '2026-09-15T17:33:09.320Z'
readOnly: true
format: date-time
description: The date and time the resource was created
updated:
anyOf:
- type: string
format: date-time
default: '2026-09-15T17:33:09.324Z'
- type: string
format: date-time
readOnly: true
format: date-time
description: The date and time the resource was last updated
required:
- _id
- workspace_id
- dataset_id
'404':
description: Datapoint not found
content:
application/json:
schema:
$ref: '#/components/schemas/HonoApiError'
components:
schemas:
TextContentPartSchema:
type: object
properties:
type:
type: string
enum:
- text
description: The type of the content part.
text:
type: string
description: The text content.
cache_control:
type: object
properties:
type:
type: string
enum:
- ephemeral
description: >-
Create a cache control breakpoint at this content block. Accepts
only the value "ephemeral".
ttl:
type: string
enum:
- 5m
- 1h
default: 5m
description: >-
The time-to-live for the cache control breakpoint. This may be
one of the following values:
- `5m`: 5 minutes
- `1h`: 1 hour
Defaults to `5m`. Only supported by `Anthropic` Claude models.
required:
- type
required:
- type
- text
title: Text content part
description: The type of the content part.
ImageContentPartSchema:
type: object
properties:
type:
type: string
enum:
- image_url
image_url:
type: object
properties:
url:
type: string
description: Either a URL of the image or the base64 encoded image data.
detail:
type: string
enum:
- low
- high
- auto
description: Specifies the detail level of the image.
required:
- url
cache_control:
type: object
properties:
type:
type: string
enum:
- ephemeral
description: >-
Create a cache control breakpoint at this content block. Accepts
only the value "ephemeral".
ttl:
type: string
enum:
- 5m
- 1h
default: 5m
description: >-
The time-to-live for the cache control breakpoint. This may be
one of the following values:
- `5m`: 5 minutes
- `1h`: 1 hour
Defaults to `5m`. Only supported by `Anthropic` Claude models.
required:
- type
required:
- type
- image_url
title: Image content part
description: An image content part
AudioContentPartSchema:
type: object
properties:
type:
type: string
enum:
- input_audio
input_audio:
type: object
properties:
data:
type: string
description: Base64 encoded audio data.
format:
type: string
enum:
- mp3
- wav
description: >-
The format of the encoded audio data. Currently supports `wav`
and `mp3`.
required:
- data
- format
required:
- type
- input_audio
title: Audio content part
description: An audio content part
FileContentPartSchema:
type: object
properties:
file_data:
type: string
description: >-
The file data as a data URI string in the format
'data:;base64,'. Example:
'data:image/png;base64,iVBORw0KGgoAAAANS...'
uri:
type: string
description: >-
URL to the file. Only supported by Anthropic Claude models for PDF
files.
mimeType:
type: string
description: MIME type of the file (e.g., application/pdf, image/png)
filename:
type: string
description: >-
The name of the file, used when passing the file to the model as a
string.
description: >-
File data for the content part. Must contain either file_data or uri,
but not both.
RefusalPartSchema:
type: object
properties:
type:
type: string
enum:
- refusal
description: The type of the content part. Always `refusal`.
refusal:
type: string
description: The refusal message generated by the model.
required:
- type
title: Refusal part
description: A message part containing a refusal message.
ReasoningPartSchema:
type: object
properties:
type:
type: string
enum:
- reasoning
description: The type of the content part. Always `reasoning`.
reasoning:
type: string
description: >-
The reasoning or thought process behind the response. Used for
chain-of-thought or extended thinking.
signature:
type: string
description: >-
Optional cryptographic signature to verify the authenticity and
integrity of the reasoning content
required:
- type
- reasoning
- signature
title: Reasoning Part
description: A message part containing reasoning or chain-of-thought content
RedactedReasoningPartSchema:
type: object
properties:
type:
type: string
enum:
- redacted_reasoning
description: The type of the content part. Always `reasoning`.
data:
type: string
description: >-
The encrypted reasoning or thought process behind the response. Used
for chain-of-thought or extended thinking.
required:
- type
- data
title: Reasoning Part
description: A message part containing reasoning or chain-of-thought content
HonoApiError:
type: object
properties:
code:
type: string
description: HTTP status code
message:
type: string
description: Error message
required:
- message
securitySchemes:
ApiKey:
type: http
scheme: bearer
bearerFormat: JWT
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.