> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchin.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Post

> Fetch a single professional post by its URL or URN, with the same fields as Get Posts

## Endpoint

```
GET /api/v1/post
```

## Authentication

Include your API key in the request header:

```bash theme={null}
X-API-Key: your-api-key-here
```

## Parameters

**postUrlOrUrn** `string` *required*

Professional post URL or URN. Accepts any of:

* **Activity URN**: `urn:li:activity:7524292314127810561`
* **ugcPost or share URN** (the `shareUrn` of a post): `urn:li:ugcPost:7524292224508096512`, `urn:li:share:7526456101387657217`
* **Post URL**: `https://www.linkedin.com/feed/update/urn:li:activity:7524292314127810561/`
  or `https://www.linkedin.com/posts/username_post-slug-activity-7524292314127810561-j6rb`

All the URNs of a post return the same post, with `id` set to its activity
URN. Anything that is not a post URL or URN is rejected with a free `400`
`INVALID_URN`.

## Response

The post itself (not wrapped in a list), with **the same fields as a post
returned by [Get Posts](https://docs.fetchin.io/api-reference/endpoint/get-posts.md)**: see the Post
object there for the full reference. The main ones:

**id** `string`

Activity URN of the post (`urn:li:activity:...`), whichever URN you passed.

**shareUrn** `string`

Share URN of the post (`urn:li:share:...` or `urn:li:ugcPost:...`).

**content** `string`

Post text. An empty string when the post has no text of its own.

**date** `string`

ISO 8601 timestamp of when the post was published.

**reactionCount** `integer`

Total reactions. `reactionsByType` breaks it down by type.

**commentCount** `integer`

Total comments.

**sharesCount** `integer`

Total reposts.

**postType** `string`

`text`, `image`, `document`, `article`, `linkedinVideo`, `job`, `event`,
`celebration`, or `repost` (see [Reposts](#reposts)).

**author** `object`

Who published the post, member or organization page: read `type`. Same
object as in Get Posts.

**profile** `object` *required*

The author, in the Get Posts `profile` shape. `profile.urn` is
`urn:li:fsd_profile:<profileId>` for a member and
`urn:li:fsd_company:<companyId>` for an organization page.

**authorProfileId** `string`

The author's profile id (`ACoAA…`), the same value as `profileId` in
[Fetch Profile](https://docs.fetchin.io/api-reference/endpoint/get-profile.md). Members only: omitted
when an organization page published the post.

**mentions** `array`

The members and companies tagged in the text. Empty when there are none.

**resharedPost** `object`

The quoted post in full, when the post quotes another one
(`resharedPostUrn` is then set too). Its `reactionCount`, `commentCount` and
`sharesCount` are included when the source provides them, which it usually
does on this endpoint.

**images** `array`

Every image of the post (`url`, `width`, `height`). `imageUrl` is the first.

**video** `object`

Video attached to the post, or `null`. `videoUrl` mirrors `video.url`.

## Reposts

A repost **without** commentary has an activity URN of its own. Pass it and it
comes back exactly as [Get Posts](https://docs.fetchin.io/api-reference/endpoint/get-posts.md) returns it
with `includeReposts=true`: `postType` is `"repost"`, `content` is `""`,
`author` and `profile` are the reposter (also named in `repostedBy`), the item
carries no counts of its own, and the original post is under `resharedPost`.

A repost **with** commentary is a post of its own: its text is in `content`
and the post it quotes is under `resharedPost`.

## Example Request

```bash cURL theme={null}
curl -X GET "https://api.fetchin.io/api/v1/post?postUrlOrUrn=urn:li:activity:7524292314127810561" \
  -H "X-API-Key: your-api-key-here"
```

```javascript JavaScript theme={null}
const params = new URLSearchParams({
  postUrlOrUrn: 'https://www.linkedin.com/feed/update/urn:li:activity:7524292314127810561/'
});

const response = await fetch(`https://api.fetchin.io/api/v1/post?${params}`, {
  headers: {
    'X-API-Key': 'your-api-key-here'
  }
});

const post = await response.json();
console.log(post);
```

```python Python theme={null}
import requests

headers = {
    'X-API-Key': 'your-api-key-here'
}

params = {
    'postUrlOrUrn': 'urn:li:activity:7524292314127810561'
}

response = requests.get(
    'https://api.fetchin.io/api/v1/post',
    headers=headers,
    params=params
)

post = response.json()
print(post)
```

```php PHP theme={null}
<?php

$apiKey = 'your-api-key-here';
$postUrlOrUrn = 'urn:li:activity:7524292314127810561';

$url = "https://api.fetchin.io/api/v1/post?postUrlOrUrn=" . urlencode($postUrlOrUrn);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . $apiKey
]);

$response = curl_exec($ch);
$post = json_decode($response, true);

curl_close($ch);
print_r($post);
?>
```

## Example Response

Trimmed to the fields documented above; the response carries every field of a
Get Posts item.

```json 200 Success theme={null}
{
  "id": "urn:li:activity:7524292314127810561",
  "shareUrn": "urn:li:ugcPost:7524292224508096512",
  "content": "Andrew travels far and wide to sit with families, hear their stories of loss, and document deaths that would otherwise go unreported. What he learns helps save lives.",
  "date": "2026-11-06T02:11:22.279Z",
  "reactionCount": 2786,
  "commentCount": 271,
  "sharesCount": 237,
  "reactionsByType": {
    "like": 2541,
    "empathy": 103,
    "appreciation": 61,
    "praise": 57,
    "interest": 23,
    "entertainment": 1
  },
  "postType": "linkedinVideo",
  "shareUrl": "https://www.linkedin.com/posts/williamhgates_andrew-travels-far-and-wide-to-sit-with-families-activity-7524292314127810561-j6rb",
  "imageUrl": null,
  "videoUrl": "https://dms.licdn.com/playlist/vid/v2/...",
  "carouselPdfUrl": null,
  "images": [],
  "video": {
    "url": "https://dms.licdn.com/playlist/vid/v2/...",
    "duration": 60066,
    "thumbnail": "https://media.licdn.com/dms/image/v2/..."
  },
  "authorType": "Person",
  "authorProfileId": "ACoAAA8BYqEBCGLg_vT_ca6mMEqkpp9nVffJ3hc",
  "author": {
    "id": "ACoAAA8BYqEBCGLg_vT_ca6mMEqkpp9nVffJ3hc",
    "publicIdentifier": "williamhgates",
    "type": "profile",
    "name": "Bill Gates",
    "url": "https://www.linkedin.com/in/williamhgates?miniProfileUrn=urn%3Ali%3Afsd_profile%3AACoAAA8BYqEBCGLg_vT_ca6mMEqkpp9nVffJ3hc",
    "info": "Chair, Gates Foundation and Founder, Breakthrough Energy",
    "numericId": "251749025"
  },
  "mentions": [],
  "contentAttributes": [],
  "profile": {
    "urn": "urn:li:fsd_profile:ACoAAA8BYqEBCGLg_vT_ca6mMEqkpp9nVffJ3hc",
    "name": "Bill Gates",
    "headline": "Chair, Gates Foundation and Founder, Breakthrough Energy",
    "url": "https://www.linkedin.com/in/williamhgates?miniProfileUrn=urn%3Ali%3Afsd_profile%3AACoAAA8BYqEBCGLg_vT_ca6mMEqkpp9nVffJ3hc",
    "imageUrl": "https://media.licdn.com/dms/image/v2/..."
  },
  "permissions": {
    "canReact": true,
    "canPostComments": true,
    "canShare": true,
    "commentingDisabled": false,
    "allowedCommentersScope": "ALL",
    "shareAudience": "PUBLIC",
    "isActivity": false,
    "rootShare": true
  }
}
```

```json 400 Bad Request theme={null}
{
  "error": "Invalid post URL or URN: 'williamhgates'. Expected urn:li:activity:<id>, urn:li:ugcPost:<id>, urn:li:share:<id> or a post URL.",
  "code": "INVALID_URN"
}
```

```json 401 Unauthorized theme={null}
{
  "error": "Invalid API key",
  "code": "INVALID_API_KEY"
}
```

```json 404 Not Found theme={null}
{
  "error": "Post not found: 7526000000000000000",
  "code": "POST_NOT_FOUND"
}
```

```json 402 Payment Required theme={null}
{
  "error": "Quota exceeded. Upgrade your plan or wait for renewal.",
  "code": "QUOTA_EXHAUSTED",
  "details": {
    "creditsRemaining": 0,
    "subscriptionCreditsRemaining": 0,
    "paygCreditsRemaining": 0,
    "buyCreditsUrl": "https://fetchin.io/credits"
  }
}
```

```json 500 Internal Server Error theme={null}
{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR"
}
```

```json 503 Service Unavailable theme={null}
{
  "error": "Service temporarily unable to serve this request. Please retry.",
  "code": "SERVICE_UNAVAILABLE"
}
```

## Errors

See [Error Handling](https://docs.fetchin.io/concepts/error-handling.md) for the full list of error codes and recommended handling.

* `400` — `MISSING_PARAMETER`, `INVALID_URN`
* `401` — `INVALID_API_KEY`
* `404` — `POST_NOT_FOUND`: the post does not exist, was deleted, or is not
  publicly visible
* `402` — `QUOTA_EXHAUSTED`
* `429` — `RATE_LIMITED`
* `500` — `INTERNAL_ERROR`
* `503` — `SERVICE_UNAVAILABLE`

## Notes

> [!NOTE]
>
> This endpoint consumes 1 credit from your credit balance per API call. Errors are free — with one exception: a `404` not found costs 1 credit. See [Quotas](https://docs.fetchin.io/concepts/quotas.md).

> [!TIP]
>
> Need the comments, reactions or reposts too? Pass the same `postUrlOrUrn` to
> [Get Post Comments](https://docs.fetchin.io/api-reference/endpoint/get-post-comments.md),
> [Get Post Reactions](https://docs.fetchin.io/api-reference/endpoint/get-post-reactions.md) or
> [Get Post Reposts](https://docs.fetchin.io/api-reference/endpoint/get-post-reposts.md).


## OpenAPI

````yaml GET /api/v1/post
openapi: 3.1.0
info:
  title: Fetchin API
  version: 1.0.0
  description: Public B2B data API for fetching posts and profile information
servers:
  - url: https://api.fetchin.io
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /api/v1/post:
    get:
      summary: Get a single post
      description: >-
        Fetch one professional post by its URL or URN, with the same fields as
        an item of GET /api/v1/posts: text, date, counts, media, author,
        mentions, and the quoted post in full when it quotes one. A repost
        without commentary comes back as `includeReposts=true` returns it on GET
        /api/v1/posts: `postType: "repost"`, the reposter as `author`, the
        original under `resharedPost`.
      parameters:
        - name: postUrlOrUrn
          in: query
          required: true
          description: >-
            Professional post URL or URN: `urn:li:activity:<id>`,
            `urn:li:ugcPost:<id>`, `urn:li:share:<id>`, or any post URL
            containing one. All three URNs of a post return the same post, with
            `id` set to its activity URN. Anything else is a free `400`
            `INVALID_URN`.
          schema:
            type: string
            example: urn:li:activity:7524292314127810561
      responses:
        '200':
          description: The post, as one item of GET /api/v1/posts
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: urn:li:activity:1234567890
                    description: >-
                      Activity URN. References the post in the
                      `urn:li:activity:*` namespace.
                  shareUrn:
                    type: string
                    example: urn:li:ugcPost:7123456789012345678
                    description: >-
                      Share URN. References the same post as `id` but in the
                      `urn:li:share:*` or `urn:li:ugcPost:*` namespace (depends
                      on the post type).
                  content:
                    type: string
                    example: This is a post content...
                  date:
                    type: string
                    format: date-time
                  reactionCount:
                    type: integer
                    description: >-
                      Omitted on a `repost` item, which has no counts of its
                      own.
                  commentCount:
                    type: integer
                    description: >-
                      Omitted on a `repost` item, which has no counts of its
                      own.
                  sharesCount:
                    type: integer
                    description: >-
                      Number of times the post was reshared. Omitted on a
                      `repost` item, which has no counts of its own.
                  imageUrl:
                    type: string
                  videoUrl:
                    type: string
                  carouselPdfUrl:
                    type: string
                  profile:
                    type: object
                    required:
                      - urn
                      - name
                      - headline
                      - url
                      - imageUrl
                    properties:
                      urn:
                        type: string
                        example: urn:li:fsd_profile:ACoAAABCDEF
                      name:
                        type: string
                        example: John Doe
                      headline:
                        type: string
                        example: Software Engineer at Tech Company
                      url:
                        type: string
                        example: https://www.linkedin.com/in/johndoe
                      imageUrl:
                        type: string
                        example: https://media.licdn.com/dms/image/...
                  resharedPostUrn:
                    type: string
                    example: urn:li:activity:7123456789012345670
                    description: >-
                      Set when the author reshared someone else's post WITH
                      their own commentary: the URN of the quoted post, which is
                      also returned in full as `resharedPost`. Absent on an
                      original post, so `!resharedPostUrn` selects originals
                      only. Also set on a `repost` item (`includeReposts=true`).
                  postType:
                    type: string
                    enum:
                      - text
                      - image
                      - document
                      - article
                      - linkedinVideo
                      - job
                      - event
                      - celebration
                      - repost
                    example: image
                    description: >-
                      Kind of content attached to the post. 'article' means a
                      link preview card is attached; long-form articles the
                      member published are NOT returned by this endpoint. 'job',
                      'event' and 'celebration' are shared cards, detailed in
                      the object of the same name. 'repost' is a repost without
                      commentary, returned only with `includeReposts=true`.
                  shareUrl:
                    type: string
                    example: >-
                      https://www.linkedin.com/posts/williamhgates_my-time-in-rwanda-...
                    description: Public permalink to the post.
                  reactionsByType:
                    type: object
                    description: >-
                      Reaction counts broken down by type. Only the types the
                      post actually received are present, and they sum to
                      `reactionCount`. Keys: `like`, `praise`, `empathy`,
                      `interest`, `appreciation`, `entertainment`, `superLike`.
                      Omitted on a `repost` item, and on a quoted post whose
                      counts the source did not provide.
                    additionalProperties:
                      type: integer
                    example:
                      like: 4139
                      empathy: 159
                      praise: 104
                      appreciation: 63
                      interest: 23
                  images:
                    type: array
                    description: >-
                      Every image of the post with its dimensions (empty for
                      non-image posts). `imageUrl` is the first one, kept for
                      backward compatibility.
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                          example: https://media.licdn.com/dms/image/...
                        width:
                          type: integer
                          example: 2048
                        height:
                          type: integer
                          example: 1365
                  video:
                    type:
                      - object
                      - 'null'
                    description: >-
                      Video attached to the post, or null. `videoUrl` mirrors
                      `video.url`.
                    properties:
                      url:
                        type: string
                        example: https://dms.licdn.com/playlist/vid/...
                      duration:
                        type: integer
                        example: 60000
                        description: Duration in milliseconds.
                      thumbnail:
                        type:
                          - string
                          - 'null'
                      progressiveStreams:
                        type: array
                        description: Available renditions (bitrate/resolution variants).
                        items:
                          type: object
                  authorProfileId:
                    type: string
                    example: ACoAAA8BYqEBCGLg_vT_ca6mMEqkpp9nVffJ3hc
                    description: >-
                      Author id, the same value as the `profileId` returned by
                      `/profile`.
                  authorType:
                    type: string
                    enum:
                      - Person
                      - Company
                    example: Person
                    description: >-
                      Whether the post was published by a member or by an
                      organization page.
                  permissions:
                    type: object
                    description: What the post allows, as published.
                    properties:
                      canReact:
                        type: boolean
                      canPostComments:
                        type: boolean
                      canShare:
                        type: boolean
                      commentingDisabled:
                        type: boolean
                      allowedCommentersScope:
                        type: string
                        example: ALL
                      shareAudience:
                        type: string
                        example: PUBLIC
                      isActivity:
                        type: boolean
                      rootShare:
                        type: boolean
                        description: False when the post quotes another one.
                  author:
                    type: object
                    description: >-
                      Who published the item, member or organization page. On a
                      `repost` item it is the reposting profile; inside
                      `resharedPost`, the original author.
                    properties:
                      type:
                        type: string
                        enum:
                          - profile
                          - company
                      id:
                        type: string
                        description: >-
                          The profile id (`ACoAA...`) for a person, the numeric
                          company id for a page.
                      name:
                        type: string
                      url:
                        type: string
                        description: >-
                          Professional profile URL, or the company page URL
                          without a `/posts` suffix.
                      info:
                        type: string
                        description: >-
                          The headline for a person, the follower line for a
                          page (e.g. "29,282,565 followers"), as the feed
                          renders it.
                      followerCount:
                        type: number
                        description: >-
                          Companies only: the follower count `info` states, as a
                          number.
                        example: 29282565
                      publicIdentifier:
                        type: string
                        description: 'Persons only: profile slug.'
                      universalName:
                        type: string
                        description: 'Companies only: page slug.'
                      numericId:
                        type: string
                        description: >-
                          Numeric member or company id, when the feed carries
                          it.
                      avatar:
                        type: object
                        description: Picture or logo, largest rendition.
                        properties:
                          url:
                            type: string
                          width:
                            type: integer
                          height:
                            type: integer
                  mentions:
                    type: array
                    description: >-
                      The members and companies tagged in the text, one entry
                      each. Empty when there are none.
                    items:
                      type: object
                      required:
                        - type
                        - id
                        - name
                        - url
                      properties:
                        type:
                          type: string
                          enum:
                            - person
                            - company
                        id:
                          type: string
                          description: >-
                            The profile id (`ACoAA...`) for a person, the
                            numeric company id for a company.
                        publicIdentifier:
                          type: string
                          description: Persons only.
                        firstName:
                          type: string
                          description: Persons only.
                        lastName:
                          type: string
                          description: Persons only.
                        universalName:
                          type: string
                          description: Companies only.
                        name:
                          type: string
                        url:
                          type: string
                  contentAttributes:
                    type: array
                    description: >-
                      Annotated ranges of `content`: tags, mentions, hashtags
                      and links. `start` and `length` index into `content`.
                    items:
                      type: object
                      properties:
                        start:
                          type: integer
                        length:
                          type: integer
                        type:
                          type: string
                          description: >-
                            Kind of range, e.g. `COMPANY_NAME`,
                            `PROFILE_MENTION`, `HASHTAG`, `HYPERLINK`.
                        hyperlink:
                          type: string
                          description: Where a link range points.
                        hashtag:
                          type: string
                        company:
                          type: object
                          description: The resolved company of a `COMPANY_NAME` range.
                          properties:
                            id:
                              type: string
                            name:
                              type: string
                            url:
                              type: string
                        profile:
                          type: object
                          description: The resolved member of a `PROFILE_MENTION` range.
                          properties:
                            id:
                              type: string
                            firstName:
                              type: string
                            lastName:
                              type: string
                            url:
                              type: string
                            publicIdentifier:
                              type: string
                  job:
                    type: object
                    description: >-
                      The shared job, on `postType: "job"`. Each field is
                      present when the card carries it.
                    properties:
                      id:
                        type: string
                        example: '4012345678'
                      url:
                        type: string
                        example: https://www.linkedin.com/jobs/view/4012345678/
                      title:
                        type: string
                        example: Senior Product Manager
                      companyName:
                        type: string
                        example: Microsoft
                      companyId:
                        type: string
                        description: Numeric company id.
                        example: '1035'
                      companyUrl:
                        type: string
                        example: https://www.linkedin.com/company/microsoft/
                      location:
                        type: string
                        example: Redmond, WA
                      companyLogoUrl:
                        type: string
                  event:
                    type: object
                    description: >-
                      The shared event, on `postType: "event"`. Each field is
                      present when the card carries it. No timestamp is
                      available for the event.
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      dateText:
                        type: string
                        description: >-
                          The date line exactly as displayed, time zone
                          included.
                        example: Sun, Sep 6, 5:30 AM - 6:30 AM UTC
                      location:
                        type: string
                      url:
                        type: string
                      bannerUrl:
                        type: string
                  celebration:
                    type: object
                    description: >-
                      The celebration card, on `postType: "celebration"`. Each
                      field is present when the card carries it.
                    properties:
                      headline:
                        type: string
                      subtitle:
                        type: string
                      imageUrl:
                        type: string
                  resharedPost:
                    type: object
                    description: >-
                      The quoted post in full, whenever `resharedPostUrn` is
                      set: the same shape as an item of `posts`. Its
                      `reactionCount`, `commentCount`, `sharesCount`,
                      `reactionsByType` and `reactionTypeCounts` are OMITTED
                      when the source did not provide them - usually the case
                      for a quoted post - never reported as 0.
                    additionalProperties: true
                  repostedBy:
                    type: object
                    description: 'Only on a `postType: "repost"` item: who reposted.'
                    properties:
                      name:
                        type: string
                      url:
                        type: string
                      publicIdentifier:
                        type: string
                        description: When a person reposted.
                      universalName:
                        type: string
                        description: When a page reposted.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  responses:
    BadRequest:
      description: Bad request - a required parameter is missing or a value is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingParameter:
              value:
                error: Missing profileUrlOrUrn parameter
                code: MISSING_PARAMETER
            invalidParameter:
              value:
                error: limit must be a number between 1 and 100
                code: INVALID_PARAMETER
            invalidUrn:
              value:
                error: 'Invalid URN format: urn:li:member:123456789'
                code: INVALID_URN
    Unauthorized:
      description: Unauthorized - the X-API-Key header is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingApiKey:
              value:
                error: Missing API key. Include X-API-Key header.
                code: UNAUTHENTICATED
            invalidApiKey:
              value:
                error: Invalid API key
                code: INVALID_API_KEY
    PaymentRequired:
      description: >-
        Payment required - you are out of credits (QUOTA_EXHAUSTED): the plan
        allowance for the current period is spent AND no pay-as-you-go credits
        are left. Buy pay-as-you-go credits (self-serve,
        https://fetchin.io/credits), upgrade your plan, or wait for renewal;
        retrying will not help and no Retry-After is sent. Distinct from the
        per-second rate limit, which is a 429 (RATE_LIMITED).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            quotaExhausted:
              value:
                error: Quota exceeded. Upgrade your plan or wait for renewal.
                code: QUOTA_EXHAUSTED
                details:
                  creditsRemaining: 0
                  subscriptionCreditsRemaining: 0
                  paygCreditsRemaining: 0
                  buyCreditsUrl: https://fetchin.io/credits
    NotFound:
      description: >-
        Not found - the request was served successfully but the requested
        professional entity does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            profileNotFound:
              value:
                error: LinkedIn profile not found
                code: PROFILE_NOT_FOUND
            postNotFound:
              value:
                error: Unable to find post from url
                code: POST_NOT_FOUND
            companyNotFound:
              value:
                error: Unable to find company slug from urn
                code: COMPANY_NOT_FOUND
    TooManyRequests:
      description: >-
        Too many requests - your per-second rate limit (RATE_LIMITED) was
        exceeded. Back off and retry, honoring the Retry-After header. (Running
        out of credits is a separate 402 PaymentRequired / QUOTA_EXHAUSTED, and
        buying credits never raises this per-second limit.)
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            rateLimited:
              value:
                error: Rate limit exceeded. Try again later.
                code: RATE_LIMITED
    InternalError:
      description: >-
        Internal server error - an unexpected error occurred in our API. Safe to
        retry; contact support if it persists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            internalError:
              value:
                error: Internal server error
                code: INTERNAL_ERROR
    ServiceUnavailable:
      description: >-
        Service unavailable - our API is temporarily unable to serve this
        request (capacity exhausted or overloaded). This is on our side, not
        yours and not an upstream service outage. Retry with backoff, honoring
        the Retry-After header.
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying the request.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            serviceUnavailable:
              value:
                error: >-
                  Service temporarily unable to serve this request. Please
                  retry.
                code: SERVICE_UNAVAILABLE
  schemas:
    Error:
      type: object
      required:
        - error
        - code
      properties:
        error:
          type: string
          description: >-
            Human-readable description of what went wrong. For display/logging;
            do not branch on this string.
        code:
          type: string
          enum:
            - MISSING_PARAMETER
            - INVALID_PARAMETER
            - INVALID_URN
            - UNAUTHENTICATED
            - INVALID_API_KEY
            - FORBIDDEN
            - NOT_FOUND
            - PROFILE_NOT_FOUND
            - POST_NOT_FOUND
            - COMPANY_NOT_FOUND
            - ENDPOINT_REMOVED
            - RATE_LIMITED
            - QUOTA_EXHAUSTED
            - INTERNAL_ERROR
            - UPSTREAM_ERROR
            - SERVICE_UNAVAILABLE
            - UPSTREAM_TIMEOUT
          description: >-
            Stable, machine-readable error code. Branch your integration on this
            value, not on the HTTP status alone or the message text.
        details:
          type: object
          additionalProperties: true
          description: >-
            Optional structured context. On QUOTA_EXHAUSTED it carries the
            balance breakdown at the moment of the rejection - creditsRemaining,
            subscriptionCreditsRemaining, paygCreditsRemaining - plus
            buyCreditsUrl, the self-serve page for buying more credits. Always
            additive and never guaranteed: read it for diagnostics and logs, but
            branch on `code` and do not require any field of it.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.