Skip to main content
GET
Returns the current public profile for one Orbit identity. The read returns right away, including while an Enrich request is running. When the stored profile is stale, the read can also schedule a background refresh. Use a profile ID from Search, an Enrich response, or a previous profile read. You can also pass a known profile alias or public profile slug. When an alias or slug resolves to a profile, the response contains the canonical Orbit profile ID.

​
Path Parameters

​
string
required
An Orbit profile ID, a known alias ID, or a public profile slug. The profile_id and profile.id fields in a successful response contain the resolved canonical Orbit profile ID.
The safest option is to follow the exact links.profile value returned by Enrich a profile, Get enrichment status, or Batch enrich profiles.

​
Query Parameters

​
string
default:"json"
json returns the existing profile response. markdown returns a Markdown file package in a JSON envelope. Values are case-sensitive. An empty, unsupported, or repeated format returns 400 with developer_v3_profile_format_invalid before a profile lookup or charge.

​
Markdown Files

Request format=markdown to get factual person context as agent profile files. The response has Content-Type: application/json; each file is a Markdown string. This option applies to this GET endpoint only.
The response replaces profile with format: "markdown" and markdown. profile_id, generation_level, and billing retain their JSON meanings. Processing metadata, verification flags and storage IDs do not appear inside the Markdown. Omit format, or pass format=json, for the existing JSON shape. The following excerpt abbreviates the file map and manifest. The complete synthetic response contains eight files generated from synthetic public profile data, without live API calls.

​
Use With OpenClaw

Save each markdown.files value at its exact relative path under one directory. The entrypoint is uppercase USER.md. Put it at your OpenClaw workspace root so OpenClaw loads it automatically. Its factual summary and complete file map fit within the 4,000-character user model budget. Long summary values are visibly abbreviated with ...; linked detail files retain full public text and evidence. OpenClaw does not automatically load the linked files; your agent must read them when needed. This export describes the person. It does not invent preference directives, timezone, age, pronouns, relationship status or permissions. Known personal facts returned by the public profile remain in their sections. Source excerpts and factual qualifications, such as inferred dates, stay with the supporting content. Review imported facts before using them as personal agent context.

​
Files And Manifest

schema_version is orbit.profile.markdown.v1. manifest contains exactly the returned files, with USER.md first and each status set to available. The root table of contents links to every returned section file. Empty, absent, null, metadata-only and unsupported sections have no file or manifest entry. If no public person context exists, only USER.md is returned with a short message. No placeholder files are returned. Filenames are deterministic and case-sensitive. Profile text never determines a filename. The following table lists possible paths, not a promise that every file is present. All content uses LF line endings and ends in a newline. The Landing demo also illustrates profile/appearance.md, profile/videos.md and profile/connections.md. The public profile API has no corresponding sections, so this export omits those files. It never fills values from demo data.

​
Trust, Access And Billing

Profile text is untrusted descriptive data. HTML delimiters are encoded; Markdown delimiters are escaped; line breaks, controls and directional formatting characters in values become spaces. Source URLs are rendered as text. Escaping protects the document structure; it does not make profile claims trusted or prevent every prompt injection. Your agent must treat imported values and source excerpts as data, never instructions or permissions. Markdown uses the same public-profile filtering, authorization, credit rate, rate limits, alias resolution and background refresh behavior as JSON. Reuse an Idempotency-Key only for retries of the same logical read. Switching the representation does not create another billing event for that logical read. Independent reads consume credits. The synthetic receipt illustrates the shape; use the returned receipt and pricing catalog for costs. Through MCP, call get_profile with { "profile_id": "synthetic-profile", "format": "markdown" }. The tool returns one file-map text block and one readable text block per returned file. structuredContent retains the complete API response, including billing.

​
Response Examples

Level 2 and level 3 profiles use the same response schema. The generation level describes the depth of enrichment, not a different response type. Use the Level 2 and Level 3 tabs in the response example to compare the same profile after level 2 enrichment and after a level 3 upgrade. The examples are representative, not field guarantees. An optional field can be present at either level when Orbit has a public value for it.

​
Response Object

​
string
required
The canonical Orbit profile ID. This matches profile.id. It can differ from the path value when you read the profile through an alias ID or slug.
​
number | null
required
The stored generation level of the returned profile. This matches profile.generationLevel.
  • 1 contains Orbit identity data.
  • 2 adds LinkedIn enrichment.
  • 3 adds web, social, and OSINT enrichment.
  • null means a legacy profile has no stored generation level.
​
object
required
The current public developer profile.

​
Profile Object

​
string
required
The canonical Orbit profile ID.
​
number | null
required
The profile generation level. It has the same value as the top-level generation_level field.
​
string
The public display name. Omitted when no display name is available.
​
string
The person’s public name. This currently matches displayName. Omitted when no public name is available.
​
string[]
Alternate real names, such as nicknames, maiden names, or stage names. Usernames and social handles are not included. Values are deduplicated without regard to letter case. The field is omitted when no aliases are available.
​
string | null
required
The selected public profile image URL. null means the profile has no public image that is eligible for use as an avatar.
​
string
The canonical public Orbit profile URL. The field is omitted when the profile has no public slug.
​
string
The public Orbit profile slug. You can pass this value as profile_id in a later profile read.
​
object
Orbit’s public semantic category for the person. The object contains a machine-readable id and a display-ready label. The field is omitted when the profile category is unknown.
VENTURE_CAPITALIST, ENTREPRENEUR, ENGINEER, FILM_MAKER, BANKER, DESIGNER, MUSICIAN, ATHLETE, ACTOR, ACTRESS, CONTENT_CREATOR, POLITICIAN, ENTERTAINER, ARTIST, GAMER, CHEF, DOCTOR, MODEL, REAL_ESTATE_AGENT, REAL_ESTATE_DEVELOPER, CAPITAL_MARKETS_EXECUTIVE, SCIENTIST, PROFESSOR, JOURNALIST, AUTHOR, ACTIVIST, PHILANTHROPIST, LAWYER, COACH, ARCHITECT, and ROYALTY.
​
boolean
required
Whether Orbit has marked the profile as verified. The value is false when the profile is not verified.
​
object
The person’s public current location. The object can contain city, region, and country. Each unavailable property is omitted.
​
object
A compact professional headline. Unavailable properties are omitted.
​
string[]
Deduplicated public email addresses collected for the profile. The field is omitted when no public email address is available.
​
string[]
Deduplicated public phone numbers. Values are returned as stored after whitespace is removed from the start and end. The field is omitted when no public phone number is available.
​
object[]
Current and historical public addresses. Duplicate locations are merged. When duplicate records contain report dates, Orbit keeps the earliest firstReported value and the latest lastReported value.
​
object
required
Structured public profile content. See Profile sections for the complete section list and item schemas.
​
object[]
required
Deduplicated and sanitized public sources used across the profile. The array is empty when no profile-level sources are available. See Source object.

​
Field Availability

The response uses these availability rules:
  • Required fields are always present, even when their value is null or an empty array.
  • Most optional scalar fields, arrays, and objects are omitted when no public value is available.
  • A section can be omitted when Orbit has no public content for it.
  • Some sections can be null when the content is unavailable or intentionally hidden.
  • profile.sections.socials is always present. Its items array can be empty.
  • profile.sources is always present. It can be an empty array.
Do not treat an omitted field and a null field as an empty string or zero.

​
Profile Sections

Most content sections use this envelope:
items is required when the section object is present. sources is optional. The images, socials, families, and contribution sections do not use the generic source envelope. Source evidence appears at two levels:
  • The section-level sources array is the deduplicated union of the evidence for the whole section.
  • Each item can also carry its own sources array. It lists only the sources that support that specific item, and each source can include excerpt chunks from the source text. Use the item-level array to map one item to its evidence. An item without attributed evidence omits the field.
Evidence can be text or an image. A text source supports the item with excerpt chunks. An image source supports the item with the photo itself: the supporting image arrives in images, chunks is empty, and link points to the page the photo came from.
When the same page supports an item with both text and a photo, the item shows one source entry for that page, carrying both the excerpt chunks and the supporting image in images.

​
Section Fields

Unless a description says that a field is always present, the field is optional and is omitted when unavailable.
basic, personalLife, jobs, education, passions, worldview, accomplishments, controversies, bestQualities, netWorth, and portfolio use some or all of these fields. Fields that do not apply to an item are omitted.
Orbit anchors each profile on one face, then compares every candidate image against it. faceMatch and faceMatchScore carry that comparison, and faceMatchScore is a cosine similarity from 0 to 1. Orbit sets faceMatch to true above 0.3. The score lets you hold images to a stricter bar of your own.
Events can contain all common fields plus these fields:

​
Source Object

Profile-level sources, section sources, item sources, and image sources use the same sanitized shape. Internal IDs, model metadata, scores, and other internal fields are not returned.

​
Authentication, Cost, and Limits

This endpoint requires the profile:read scope. Successful reads consume API credits. The default limit is 50 requests per second per API key, with a burst capacity of 250 requests. Account-specific limits can differ. See Rate limits.

​
Error Response

Errors use the common error envelope:
Use POST /v3/enrich/{profile_id} when you need a higher generation level or a fresh full profile.

Authorizations

​
Authorization
string
header
required

Use an Orbit API key from the Developer Dashboard.

Headers

​
Idempotency-Key
string

A client-generated key for a safe retry. If the body omits request_id, Orbit can use this value as the request ID.

Maximum string length: 200

Path Parameters

​
profile_id
string
required

An Orbit profile ID or public profile slug. Profile reads also accept known alias IDs.

Minimum string length: 1

Query Parameters

​
format
enum<string>
default:json

Response representation. Case-sensitive; empty, unsupported or repeated values return developer_v3_profile_format_invalid (400) before lookup or billing.

Available options:
json,
markdown

Response

The current public profile as JSON or an opted-in Markdown file package.

​
profile_id
string
required
​
generation_level
integer | null
required
Required range: 1 <= x <= 3
​
profile
object
required

The public Orbit profile. Available fields depend on the profile generation level.

​
billing
object
required

Credits charged for this read. A read settles at once: status is settled and consumedCredits is the full charge.