Endpoints

POST /api/v1/resources/search

Retrieve datapoints for one or more social media resources.

Request Body

{
  "resources": [
    {
      "platform": "instagram",
      "type": "account",
      "identifier": "natgeo"
    }
  ]
}

Fields

Field	Type	Required	Description
`resources`	array	yes	List of resources to query
`resources[].platform`	string	yes	Platform code: `facebook`, `instagram`, `linkedin`, `threads`, `tiktok`, `x`, or `youtube`
`resources[].type`	string	yes	Resource type: `account` or `organization`. See Resource types
`resources[].identifier`	string	yes	Username or ID to look up

Resource types

Most platforms give every profile a single address, so account is the only type they accept.

LinkedIn is the exception. It keeps people and companies in separate places, and the same name can belong to both: linkedin.com/in/meta is a person’s profile, while linkedin.com/company/meta is the company. Set type to match the one you want.

Platform	Accepted types
`facebook`, `instagram`, `threads`, `tiktok`, `x`, `youtube`	`account`
`linkedin`	`account` for profiles under `/in/`, `organization` for pages under `/company/`

Use organization for any company page, including non-profits, universities, and government bodies.

{
  "resources": [
    {"platform": "linkedin", "type": "organization", "identifier": "nasa"}
  ]
}

Because both can exist under the same name, a mismatched type returns the wrong profile rather than an error. If a LinkedIn lookup comes back empty, check which address the profile actually lives at.

Constraints

Maximum 10 resources per request
Duplicate resources (same platform + type + identifier) are automatically removed

Example Request

curl -X POST https://metrika.run/api/v1/resources/search \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resources": [
      {"platform": "instagram", "type": "account", "identifier": "natgeo"},
      {"platform": "x", "type": "account", "identifier": "nasa"}
    ]
  }'

Success Response

200 OK

{
  "data": [
    {
      "platform": "instagram",
      "type": "account",
      "identifier": "natgeo",
      "status": "available",
      "metrics": {
        "followers": {
          "value": 284000000,
          "status": "available",
          "collected_at": "2026-06-27T10:00:00.000Z"
        },
        "following": {
          "value": 74,
          "status": "available",
          "collected_at": "2026-06-27T10:00:00.000Z"
        }
      }
    },
    {
      "platform": "x",
      "type": "account",
      "identifier": "nasa",
      "status": "available",
      "metrics": {
        "followers": {
          "value": 96800000,
          "status": "available",
          "collected_at": "2026-06-27T10:00:00.000Z"
        },
        "following": {
          "value": 337,
          "status": "available",
          "collected_at": "2026-06-27T10:00:00.000Z"
        }
      },
      "attributes": {
        "verified": {
          "value": true,
          "status": "available",
          "collected_at": "2026-06-27T10:00:00.000Z"
        }
      }
    }
  ]
}

The data array contains one entry per requested resource in the same order as the request. Until a resource has been resolved and collected, its entry contains only platform, type, identifier, and status, with no datapoints yet. Requesting a new resource starts background collection, so its datapoints appear on a later request once the data is ready.

The status field at the resource level indicates the availability of the resource:

Status	Description
`available`	The resource was found and data is being collected
`pending`	Data collection for this resource is in progress
`not_found`	The resource could not be found on the platform
`unavailable`	The resource is not available for this platform

The status field inside each metric indicates the availability of the data:

Status	Description
`available`	Metric data is current and ready
`unavailable`	Metric is not available for this platform
`pending`	Metric is being collected and will be available soon

Error Responses

Unauthorized

401 Unauthorized

The request did not include a valid API token. Include it in the Authorization: Bearer header.

Validation Error

422 Unprocessable Entity

{
  "errors": [
    "Resources can't be blank"
  ]
}

The request body failed validation. The errors array contains one or more descriptive messages.

Quota Exceeded

403 Forbidden

{
  "error": "You have exceeded your quota of 500 requests, resets on 2026-08-01."
}

The account’s monthly usage quota has been exhausted. The error message indicates when the allowance resets (the start of the next calendar month).

Rate Limited

429 Too Many Requests

{
  "error": "Rate limit exceeded. Please try again later."
}

The rate limit for this account has been exceeded. Back off and retry once the window resets.

Error Code Reference

Status	Description
200	Success
401	Missing or invalid API token
403	Monthly usage quota exhausted
422	Request validation failed
429	Rate limit exceeded
500	Internal server error