> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.spyglass.so/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.spyglass.so/_mcp/server.

# Get an account's posts

GET https://api.spyglass.so/v2/account/posts

Return one account's posts, fetched live. The account does not need to be indexed.
A call usually takes 10–30 seconds and starts indexing the rest of the brand's posts.
Use `POST /media` first when you already have an account id. See the Finding media guide.

Limited to 120 requests per minute per user.
Costs $0.0010 per creative returned, charged against your plan's monthly credits. The count field is what you were charged for.
The call bills a minimum of one row even when nothing matches. In that
case `count` is 0 but you are charged for one row.

Send exactly one identifier. The fields you can send depend on which
one you pick.

**`igUsername`**

| Field | Details |
| --- | --- |
| `igUsername` | Instagram handle. A leading `@` is ignored. |
| `tagged` | Optional. `true` returns posts the account is tagged in. Omit it for the account's own posts. Cannot be combined with `postType=reels`. |
| `postType` | Optional, Instagram only. `posts` (default) or `reels`. Cannot be combined with `tagged`. |
| `includeTranscript` | Optional. `true` transcribes each video and returns `transcript`. Omit it or send `false` to skip transcription. The call takes longer. |
| `limit` | Optional. Default 20, max 120. |
| `sortBy` | Ignored. Posts are always most recent. |

**`tiktokUsername`**

| Field | Details |
| --- | --- |
| `tiktokUsername` | TikTok handle. A leading `@` is ignored. |
| `includeTranscript` | Optional. `true` transcribes each video and returns `transcript`. Omit it or send `false` to skip transcription. The call takes longer. |
| `sortBy` | Optional. `most_recent` (default) or `popular`. |
| `limit` | Optional. Default 20, max 120. |

**`facebookAdLibraryId`**

| Field | Details |
| --- | --- |
| `facebookAdLibraryId` | Facebook Ad Library page id. |
| `includeTranscript` | Optional. `true` transcribes each video and returns `transcript`. Omit it or send `false` to skip transcription. The call takes longer. |
| `sortBy` | Optional. `most_recent` (default) or `most_impressions`. |
| `limit` | Optional. Default 20, max 120. |

Reference: https://docs.spyglass.so/api-reference/spyglass-api/social-media-account/posts

## Authentication

- `Authorization` header (bearer token, required) — An API key from Settings → API, prefixed sg_live_.

## Request

### Query parameters

- `igUsername` (string, optional) — Instagram handle. Exactly one of igUsername, tiktokUsername, or facebookAdLibraryId. A leading @ is ignored. sortBy is ignored.
- `tiktokUsername` (string, optional) — TikTok handle. Exactly one identifier. sortBy is optional: most_recent (default) or popular. A leading @ is ignored. Do not send tagged.
- `facebookAdLibraryId` (string, optional) — Facebook Ad Library page id. Exactly one identifier. sortBy is optional: most_recent (default) or most_impressions. Do not send tagged.
- `tagged` (enum, optional) — Only with igUsername. true returns posts the account is tagged in. Omit for the account’s own posts.
  - Allowed values: `true`, `false`
- `postType` (enum, optional) — Only with igUsername. posts (default) or reels. Cannot be combined with tagged. Rejected for other identifiers.
  - Allowed values: `posts`, `reels`
- `includeTranscript` (enum, optional) — true transcribes each video and returns transcript. Omit or false to skip transcription.
  - Allowed values: `true`, `false`
- `sortBy` (enum, optional) — Optional. With tiktokUsername: most_recent (default) or popular. With facebookAdLibraryId: most_recent (default) or most_impressions. Ignored with igUsername.
  - Allowed values: `popular`, `most_impressions`, `most_recent`
- `limit` (integer, optional, default: 20) — Maximum posts to return. Default 20, max 120.

## Response

### 200

Posts for the account.

- `count` (integer, required)
- `media` (list of AccountPostsGetResponsesContentApplicationJsonSchemaMediaItems, required)

## Errors

### 400 Bad Request Error

The request body or query string failed validation. `details` lists the offending fields.

- `error` (ErrorError, required)

### 401 Unauthorized Error

The API key is missing, malformed, unknown, or revoked.

- `error` (ErrorError, required)

### 402 Payment Required Error

The team's monthly credits are exhausted.

- `error` (ErrorError, required)

### 403 Forbidden Error

The team's subscription is inactive, or your membership of it has ended.

- `error` (ErrorError, required)

### 405 Method Not Allowed Error

The HTTP method is not supported on this path. The Allow header lists what is. HEAD is refused on metered GET endpoints because it would be billed without returning data.

- `error` (ErrorError, required)

### 429 Too Many Requests Error

Too many requests for this user on this endpoint. Carries a Retry-After header. The per-minute limit is stated on the operation.

- `error` (ErrorError, required)

### 500 Internal Server Error

Something went wrong on our side.

- `error` (ErrorError, required)

## Types

### AccountPostsGetResponsesContentApplicationJsonSchemaMediaItems

- `id` (string, required)
- `platformId` (string, required)
- `brand` (AccountPostsGetResponsesContentApplicationJsonSchemaMediaItemsBrand, required, nullable)
- `title` (string, required, nullable)
- `type` (enum, required, nullable)
  - Allowed values: `DPA`, `VIDEO`, `CAROUSEL`, `IMAGE`, `DCO`
- `mediaType` (enum, required, nullable)
  - Allowed values: `VIDEO`, `IMAGE`
- `url` (string, required, nullable)
- `urls` (list of string, required)
- `thumbnailUrl` (string, required, nullable)
- `width` (double, required, nullable)
- `height` (double, required, nullable)
- `durationInSeconds` (double, required, nullable)
- `platforms` (list of string, required)
- `hook` (string, required, nullable)
- `summary` (string, required, nullable)
- `coreAngle` (string, required, nullable)
- `targetPersona` (string, required, nullable)
- `ugcCharacter` (AccountPostsGetResponsesContentApplicationJsonSchemaMediaItemsUgcCharacter, required, nullable)
- `startAt` (string, required, nullable)
- `endAt` (string, required, nullable)
- `daysRun` (double, required, nullable)
- `categories` (list of string, required)
- `carouselCount` (double, required, nullable)
- `viewCount` (double, required, nullable)
- `likeCount` (double, required, nullable)
- `commentCount` (double, required, nullable)
- `impressionPercentile` (double, required, nullable)
- `impressionsText` (string, required, nullable)
- `painPoints` (list of string, optional)
- `sellingPoints` (list of string, optional)
- `transcript` (string, optional, nullable)

### ErrorError

- `code` (enum, required)
  - Allowed values: `invalid_request`, `invalid_api_key`, `payload_too_large`, `out_of_credits`, `membership_ended`, `subscription_inactive`, `brand_not_found`, `not_found`, `method_not_allowed`, `rate_limited`, `not_implemented`, `internal_error`
- `message` (string, required)
- `details` (list of ErrorErrorDetailsItems, optional)

### AccountPostsGetResponsesContentApplicationJsonSchemaMediaItemsBrand

- `id` (string, required)
- `name` (string, required)
- `type` (enum, required, nullable)
  - Allowed values: `BRAND`, `CREATOR`
- `thumbnailUrl` (string, required, nullable)
- `category` (string, required, nullable)
- `facebookAdLibraryId` (string, optional, nullable)
- `igUsername` (string, optional, nullable)
- `igFollowers` (double, optional, nullable)
- `tiktokUsername` (string, optional, nullable)
- `tiktokFollowers` (double, optional, nullable)
- `facebookUsername` (string, optional, nullable)

### AccountPostsGetResponsesContentApplicationJsonSchemaMediaItemsUgcCharacter

- `ageRange` (enum, required, nullable)
  - Allowed values: `0-18`, `18-24`, `25-34`, `35-44`, `45-54`, `55-64`, `65+`
- `gender` (enum, required, nullable)
  - Allowed values: `male`, `female`, `other`
- `ethnicity` (enum, required, nullable)
  - Allowed values: `White`, `Black`, `Asian`, `Hispanic`, `Middle Eastern`, `Indigenous`, `Pacific Islander`
- `description` (string, required, nullable)

### ErrorErrorDetailsItems

- `path` (string, required)
- `message` (string, required)

## Examples

### Instagram

**SDK Code**

```python Instagram
import requests

url = "https://api.spyglass.so/v2/account/posts"

querystring = {"igUsername":"nike","limit":"20"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript Instagram
const url = 'https://api.spyglass.so/v2/account/posts?igUsername=nike&limit=20';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Instagram
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.spyglass.so/v2/account/posts?igUsername=nike&limit=20"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Instagram
require 'uri'
require 'net/http'

url = URI("https://api.spyglass.so/v2/account/posts?igUsername=nike&limit=20")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java Instagram
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.spyglass.so/v2/account/posts?igUsername=nike&limit=20")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php Instagram
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.spyglass.so/v2/account/posts?igUsername=nike&limit=20', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp Instagram
using RestSharp;

var client = new RestClient("https://api.spyglass.so/v2/account/posts?igUsername=nike&limit=20");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Instagram
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.spyglass.so/v2/account/posts?igUsername=nike&limit=20")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Instagram tagged

**SDK Code**

```python Instagram tagged
import requests

url = "https://api.spyglass.so/v2/account/posts"

querystring = {"igUsername":"nike","limit":"20","tagged":"true"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript Instagram tagged
const url = 'https://api.spyglass.so/v2/account/posts?igUsername=nike&limit=20&tagged=true';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Instagram tagged
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.spyglass.so/v2/account/posts?igUsername=nike&limit=20&tagged=true"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Instagram tagged
require 'uri'
require 'net/http'

url = URI("https://api.spyglass.so/v2/account/posts?igUsername=nike&limit=20&tagged=true")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java Instagram tagged
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.spyglass.so/v2/account/posts?igUsername=nike&limit=20&tagged=true")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php Instagram tagged
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.spyglass.so/v2/account/posts?igUsername=nike&limit=20&tagged=true', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp Instagram tagged
using RestSharp;

var client = new RestClient("https://api.spyglass.so/v2/account/posts?igUsername=nike&limit=20&tagged=true");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Instagram tagged
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.spyglass.so/v2/account/posts?igUsername=nike&limit=20&tagged=true")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Instagram reels

**SDK Code**

```python Instagram reels
import requests

url = "https://api.spyglass.so/v2/account/posts"

querystring = {"igUsername":"nike","limit":"20","postType":"reels"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript Instagram reels
const url = 'https://api.spyglass.so/v2/account/posts?igUsername=nike&limit=20&postType=reels';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Instagram reels
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.spyglass.so/v2/account/posts?igUsername=nike&limit=20&postType=reels"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Instagram reels
require 'uri'
require 'net/http'

url = URI("https://api.spyglass.so/v2/account/posts?igUsername=nike&limit=20&postType=reels")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java Instagram reels
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.spyglass.so/v2/account/posts?igUsername=nike&limit=20&postType=reels")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php Instagram reels
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.spyglass.so/v2/account/posts?igUsername=nike&limit=20&postType=reels', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp Instagram reels
using RestSharp;

var client = new RestClient("https://api.spyglass.so/v2/account/posts?igUsername=nike&limit=20&postType=reels");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Instagram reels
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.spyglass.so/v2/account/posts?igUsername=nike&limit=20&postType=reels")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### TikTok

**SDK Code**

```python TikTok
import requests

url = "https://api.spyglass.so/v2/account/posts"

querystring = {"limit":"20","tiktokUsername":"nike"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript TikTok
const url = 'https://api.spyglass.so/v2/account/posts?limit=20&tiktokUsername=nike';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go TikTok
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.spyglass.so/v2/account/posts?limit=20&tiktokUsername=nike"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby TikTok
require 'uri'
require 'net/http'

url = URI("https://api.spyglass.so/v2/account/posts?limit=20&tiktokUsername=nike")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java TikTok
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.spyglass.so/v2/account/posts?limit=20&tiktokUsername=nike")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php TikTok
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.spyglass.so/v2/account/posts?limit=20&tiktokUsername=nike', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp TikTok
using RestSharp;

var client = new RestClient("https://api.spyglass.so/v2/account/posts?limit=20&tiktokUsername=nike");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift TikTok
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.spyglass.so/v2/account/posts?limit=20&tiktokUsername=nike")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Facebook Ad Library

**SDK Code**

```python Facebook Ad Library
import requests

url = "https://api.spyglass.so/v2/account/posts"

querystring = {"facebookAdLibraryId":"15087023444","limit":"20"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript Facebook Ad Library
const url = 'https://api.spyglass.so/v2/account/posts?facebookAdLibraryId=15087023444&limit=20';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Facebook Ad Library
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.spyglass.so/v2/account/posts?facebookAdLibraryId=15087023444&limit=20"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Facebook Ad Library
require 'uri'
require 'net/http'

url = URI("https://api.spyglass.so/v2/account/posts?facebookAdLibraryId=15087023444&limit=20")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java Facebook Ad Library
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.spyglass.so/v2/account/posts?facebookAdLibraryId=15087023444&limit=20")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php Facebook Ad Library
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.spyglass.so/v2/account/posts?facebookAdLibraryId=15087023444&limit=20', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp Facebook Ad Library
using RestSharp;

var client = new RestClient("https://api.spyglass.so/v2/account/posts?facebookAdLibraryId=15087023444&limit=20");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Facebook Ad Library
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.spyglass.so/v2/account/posts?facebookAdLibraryId=15087023444&limit=20")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```