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

# API

> Unified asynchronous social data collection API.

# API

The API provides a consistent request flow for social data collection:

```text theme={null}
submit -> task_id -> task status/results/files
```

## Authentication

```http theme={null}
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Submit Endpoints

Each product API has its own resource path:

| Platform  | API             | Endpoint                             |
| --------- | --------------- | ------------------------------------ |
| Instagram | Posts           | `POST /v1/instagram/posts`           |
| Instagram | Reels           | `POST /v1/instagram/reels`           |
| Instagram | Search          | `POST /v1/instagram/search`          |
| Instagram | Followers Count | `POST /v1/instagram/followers-count` |
| Facebook  | Pages           | `POST /v1/facebook/pages`            |
| Facebook  | Posts           | `POST /v1/facebook/posts`            |

## Common Submit Body

Input fields are sent directly in the JSON body.

```json theme={null}
{
  "urls": ["https://www.instagram.com/p/POST_CODE/"],
  "results_limit": 10,
  "callback_url": "https://your-domain.com/webhook"
}
```

`callback_url` is optional. If provided, SocQ sends a POST request after the task reaches a terminal state. See [Callbacks](/api-manual/agent-api/callbacks) for the payload shape.

## Result Storage

SocQ stores two forms of results:

| Storage            | Purpose                                                   |
| ------------------ | --------------------------------------------------------- |
| Normalized records | Returned by `/v1/tasks/{task_id}` after the task succeeds |
| Raw JSONL file     | Download from `/v1/tasks/{task_id}/files`                 |

Raw files use this path format:

```text theme={null}
agent-results/{task_id}/raw_jsonl.jsonl.gz
```

## Billing

Agent APIs are billed by returned result record. The submit request may reserve credits from `results_limit` or the number of submitted URLs/usernames; after the task finishes, SocQ settles the final charge from the actual `result_count` and returns any unused reserved credits.