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

# REST API v1

> Use Superdata's Profile, Profile Posts, Company, and Company Posts APIs.

Superdata offers four focused products through one synchronous REST API: Profile, Profile Posts, Company, and Company Posts. Every endpoint returns structured data directly and does not create background jobs or require polling.

## Base URL and authentication

```text theme={null}
https://api.superdata.so
```

Every request requires an API key in the authorization header:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

Create and revoke keys from the Superdata API dashboard. API keys are not accepted in query parameters.

## Endpoints

### Get a profile

[View the complete Profile API reference →](/reference/profile-api)

```http theme={null}
GET /v1/profile
```

Provide at least one identifier. When several are supplied, precedence is `url`, `person.id`, `user_id`, then `profile_id`.

| Parameter           | Type             | Default   | Description                                                                    |
| ------------------- | ---------------- | --------- | ------------------------------------------------------------------------------ |
| `url`               | URL              | —         | Public LinkedIn `/in/` or `/pub/` profile URL                                  |
| `person.id`         | positive integer | —         | Numeric person ID accepted by Superdata; the dot is part of the parameter name |
| `user_id`           | positive integer | —         | LinkedIn user ID                                                               |
| `profile_id`        | positive integer | —         | LinkedIn profile ID                                                            |
| `strategy`          | enum             | `cached`  | `cached`, `fetch`, `strict`, or `besteffort`                                   |
| `maxage`            | positive integer | —         | Maximum cache age in seconds for `strict` or `besteffort`                      |
| `experience_filter` | enum             | `default` | `default`, `current`, `revisions`, or `distincts`                              |
| `education_filter`  | enum             | `default` | `default`, `current`, `revisions`, or `distincts`                              |
| `summary_filter`    | enum             | `default` | `default` or `last_complete`                                                   |

```bash theme={null}
curl --request GET \
  --url "https://api.superdata.so/v1/profile?url=https%3A%2F%2Fwww.linkedin.com%2Fin%2Fsatyanadella&strategy=cached" \
  --header "Authorization: Bearer YOUR_API_KEY"
```

### Get a company

[View the complete Company API reference →](/reference/company-api)

```http theme={null}
GET /v1/company
```

Provide at least one identifier. Precedence is `url`, `company.id`, then `org_id`.

| Parameter    | Type             | Default  | Description                                                                     |
| ------------ | ---------------- | -------- | ------------------------------------------------------------------------------- |
| `url`        | URL              | —        | Public LinkedIn `/company/` or `/school/` URL                                   |
| `company.id` | positive integer | —        | Numeric company ID accepted by Superdata; the dot is part of the parameter name |
| `org_id`     | positive integer | —        | LinkedIn company or school ID                                                   |
| `strategy`   | enum             | `cached` | `cached`, `fetch`, `strict`, or `besteffort`                                    |
| `maxage`     | positive integer | —        | Maximum cache age in seconds for `strict` or `besteffort`                       |

```bash theme={null}
curl --request GET \
  --url "https://api.superdata.so/v1/company?url=https%3A%2F%2Fwww.linkedin.com%2Fcompany%2Fmicrosoft&strategy=cached" \
  --header "Authorization: Bearer YOUR_API_KEY"
```

### Get profile posts

[View the complete Profile Posts API reference →](/reference/profile-posts-api)

```http theme={null}
GET /v1/profile/posts
```

Provide `url`, `person.id`, or `profile_id`, in that precedence order.

| Parameter    | Type             | Default  | Description                                   |
| ------------ | ---------------- | -------- | --------------------------------------------- |
| `url`        | URL              | —        | Public LinkedIn `/in/` or `/pub/` profile URL |
| `person.id`  | positive integer | —        | Numeric person ID accepted by Superdata       |
| `profile_id` | positive integer | —        | LinkedIn profile ID                           |
| `strategy`   | enum             | `cached` | `cached` or `fetch`                           |
| `sort_field` | enum             | `id`     | `id` or `post_date`                           |
| `offset`     | integer          | `0`      | Result offset; minimum `0`                    |
| `page_size`  | integer          | `10`     | Results per page; minimum `1`, maximum `100`  |

```bash theme={null}
curl --request GET \
  --url "https://api.superdata.so/v1/profile/posts?url=https%3A%2F%2Fwww.linkedin.com%2Fin%2Fsatyanadella&page_size=10&sort_field=post_date" \
  --header "Authorization: Bearer YOUR_API_KEY"
```

### Get company posts

[View the complete Company Posts API reference →](/reference/company-posts-api)

```http theme={null}
GET /v1/company/posts
```

Provide `url`, `company.id`, or `org_id`, in that precedence order.

| Parameter    | Type             | Default  | Description                                   |
| ------------ | ---------------- | -------- | --------------------------------------------- |
| `url`        | URL              | —        | Public LinkedIn `/company/` or `/school/` URL |
| `company.id` | positive integer | —        | Numeric company ID accepted by Superdata      |
| `org_id`     | positive integer | —        | LinkedIn company or school ID                 |
| `strategy`   | enum             | `cached` | `cached` or `fetch`                           |
| `sort_field` | enum             | `id`     | `id` or `post_date`                           |
| `offset`     | integer          | `0`      | Result offset; minimum `0`                    |
| `page_size`  | integer          | `10`     | Results per page; minimum `1`, maximum `100`  |

```bash theme={null}
curl --request GET \
  --url "https://api.superdata.so/v1/company/posts?url=https%3A%2F%2Fwww.linkedin.com%2Fcompany%2Fmicrosoft&page_size=10&sort_field=post_date" \
  --header "Authorization: Bearer YOUR_API_KEY"
```

## Cache strategies

| Strategy     | Behavior                                                                                            |
| ------------ | --------------------------------------------------------------------------------------------------- |
| `cached`     | Return an available fresh cache result without fetching the source                                  |
| `fetch`      | Fetch a fresh result from the source                                                                |
| `strict`     | Use cache only when it is newer than `maxage`; otherwise fetch fresh                                |
| `besteffort` | Use cache when newer than `maxage`; otherwise fetch and fall back to stale cache if the fetch fails |

`strict` and `besteffort` are supported by Profile and Company. Post endpoints support `cached` and `fetch`.

## Responses

A successful profile or company request returns the provider fields under `data`:

```json theme={null}
{
  "request_id": "req_01...",
  "data": {},
  "meta": {
    "source": "linkedin",
    "cached": false,
    "credits_used": 1
  }
}
```

Post responses include `data.posts` and pagination metadata. Additional provider fields remain under `data`.

```json theme={null}
{
  "request_id": "req_01...",
  "data": { "posts": [] },
  "meta": {
    "source": "linkedin",
    "cached": false,
    "credits_used": 1,
    "pagination": {
      "offset": 0,
      "page_size": 10,
      "next_offset": null,
      "has_more": false
    }
  }
}
```

Errors always use one safe envelope:

```json theme={null}
{
  "error": {
    "code": "INVALID_LINKEDIN_URL",
    "message": "Please provide a valid LinkedIn profile URL.",
    "request_id": "req_01..."
  }
}
```

| Status | Meaning                                                                         |
| ------ | ------------------------------------------------------------------------------- |
| `400`  | Missing or invalid parameters                                                   |
| `401`  | Missing, invalid, revoked, or expired API key                                   |
| `403`  | API key does not have access                                                    |
| `404`  | Requested resource was not found                                                |
| `429`  | Rate or credit limit was exceeded                                               |
| `500`  | Unexpected internal error                                                       |
| `502`  | Upstream provider error                                                         |
| `512`  | `TEMPORARY_FETCH_FAILURE`; retry the request                                    |
| `513`  | `SOURCE_NOT_FOUND`; the source was deleted or moved, so do not retry repeatedly |

Every response includes `X-Request-Id`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. Include the request ID when contacting support.