OD. Media & Technology Account usage API

openapi: 3.2.0
info:
  title: ScrapeAtlas Account usage API
  version: 0.1.0
  description: ScrapeAtlas turns public social media data into structured JSON. Get profiles, posts, videos, comments, ads and products through one API for your apps and AI agents. Authenticate at api.scrapeatlas.com with a customer x-api-key. Availability is documented per platform; local worker origins are operator references.
servers:
- url: https://api.scrapeatlas.com
tags:
- name: Account usage
  description: Read your account’s recorded API usage and request activity.
paths:
  /v1/usage:
    get:
      operationId: accountUsage
      tags:
      - Account usage
      summary: Get account usage
      description: Return daily UTC request and error totals by platform for the authenticated account. Choose a period with days. Accepts a customer API key or first-party dashboard session. This account operation costs 0 credits.
      servers:
      - url: https://api.scrapeatlas.com
        description: ScrapeAtlas public API
      security:
      - usage: []
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 30
          default: 30
        description: Number of UTC calendar days including today, 1–30.
        example: 7
      responses:
        '200':
          description: Inspect the response status and failure or coverage fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/usageResponseSchema'
              example:
                success: true
                status: partial
                requestId: 00000000-0000-4000-8000-000000000001
                coverage:
                  complete: false
                  warnings:
                  - best_effort_usage
                  - ingestion_delay
                data:
                  days: 7
                  rows:
                  - day: '2026-09-12'
                    platform: telegram
                    requests: 2
                    errors: 1
                    duration_ms_sum: 60
        '400':
          description: Request could not complete; inspect error or failure.code.
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/gatewayFailure'
        '401':
          description: Request could not complete; inspect error or failure.code.
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/gatewayFailure'
        '429':
          description: Request could not complete; inspect error or failure.code.
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/gatewayFailure'
        '503':
          description: Request could not complete; inspect error or failure.code.
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/gatewayFailure'
  /v1/activity:
    get:
      operationId: accountActivity
      tags:
      - Account usage
      summary: Get account activity
      description: Return recorded request metadata for the authenticated account, newest first. Filter by UTC window, platform, operation and HTTP status; continue with the returned cursor. Accepts customer API keys and first-party dashboard sessions. This account operation costs 0 credits.
      servers:
      - url: https://api.scrapeatlas.com
        description: ScrapeAtlas public API
      security:
      - usage: []
      parameters:
      - name: start
        in: query
        required: false
        schema:
          type: string
          format: date-time
          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
          x-runtime-refinement: true
        description: Inclusive UTC timestamp, with milliseconds and Z.
      - name: end
        in: query
        required: false
        schema:
          type: string
          format: date-time
          pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
          x-runtime-refinement: true
        description: Exclusive UTC timestamp, with milliseconds and Z.
      - name: platform
        in: query
        required: false
        schema:
          type: string
          pattern: ^[a-z][a-z0-9-]{0,39}$
        description: Catalog platform identifier.
      - name: operation
        in: query
        required: false
        schema:
          type: string
          pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$
        description: Catalog operation identifier.
      - name: status
        in: query
        required: false
        schema:
          type: string
          pattern: ^[1-5](?:\d{2}|xx)$
        description: Exact HTTP status or class such as 200 or 4xx.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
        description: Page size.
        example: 50
      - name: cursor
        in: query
        required: false
        schema:
          type: string
          minLength: 1
          maxLength: 2048
        description: Continuation cursor returned by the previous page; reuse the same filters and page size.
      responses:
        '200':
          description: Inspect the response status and failure or coverage fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/activityResponseSchema'
              example:
                success: true
                status: partial
                requestId: 00000000-0000-4000-8000-000000000001
                coverage:
                  complete: false
                  warnings:
                  - best_effort_usage
                  - ingestion_delay
                data:
                  start: '2026-09-13T00:00:00.000Z'
                  end: '2026-09-14T00:00:00.000Z'
                  rows:
                  - event_id: 00000000-0000-4000-8000-000000000002
                    timestamp: '2026-09-13T12:00:00.000Z'
                    platform: telegram
                    operation: telegramChannel
                    method: GET
                    path: /v1/telegram/channel
                    status: 200
                    duration_ms: 42
                  nextCursor: null
        '400':
          description: Request could not complete; inspect error or failure.code.
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/gatewayFailure'
        '401':
          description: Request could not complete; inspect error or failure.code.
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/gatewayFailure'
        '429':
          description: Request could not complete; inspect error or failure.code.
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/gatewayFailure'
        '503':
          description: Request could not complete; inspect error or failure.code.
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/gatewayFailure'
components:
  schemas:
    usageResponseSchema:
      type: object
      properties:
        success:
          type: boolean
          const: true
        status:
          type: string
          const: partial
        requestId:
          type: string
          format: uuid
        coverage:
          type: object
          properties:
            complete:
              type: boolean
              const: false
            warnings:
              type: array
              items:
                type: string
          required:
          - complete
          - warnings
          additionalProperties: false
        data:
          type: object
          properties:
            days:
              type: integer
              minimum: 1
              maximum: 30
            rows:
              type: array
              items:
                type: object
                properties:
                  day:
                    type: string
                    pattern: ^\d{4}-\d{2}-\d{2}$
                  platform:
                    type: string
                    pattern: ^[a-z][a-z0-9-]{0,39}$
                  requests:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  errors:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  duration_ms_sum:
                    type: number
                    minimum: 0
                required:
                - day
                - platform
                - requests
                - errors
                - duration_ms_sum
                additionalProperties: false
                x-runtime-refinement: true
              maxItems: 2048
          required:
          - days
          - rows
          additionalProperties: false
      required:
      - success
      - status
      - requestId
      - coverage
      - data
      additionalProperties: false
    activityResponseSchema:
      type: object
      properties:
        success:
          type: boolean
          const: true
        status:
          type: string
          const: partial
        requestId:
          type: string
          format: uuid
        coverage:
          type: object
          properties:
            complete:
              type: boolean
              const: false
            warnings:
              type: array
              items:
                type: string
                enum:
                - best_effort_usage
                - ingestion_delay
          required:
          - complete
          - warnings
          additionalProperties: false
        data:
          type: object
          properties:
            start:
              type: string
              format: date-time
              pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
              x-runtime-refinement: true
            end:
              type: string
              format: date-time
              pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
              x-runtime-refinement: true
            rows:
              type: array
              items:
                type: object
                properties:
                  event_id:
                    type: string
                    format: uuid
                  platform:
                    type: string
                    pattern: ^[a-z][a-z0-9-]{0,39}$
                  operation:
                    type: string
                    pattern: ^[A-Za-z][A-Za-z0-9_-]{0,63}$
                  status:
                    type: integer
                    minimum: 100
                    maximum: 599
                  duration_ms:
                    type: integer
                    minimum: 0
                    maximum: 4294967295
                  timestamp:
                    type: string
                    format: date-time
                    pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
                    x-runtime-refinement: true
                  method:
                    anyOf:
                    - type: string
                      enum:
                      - GET
                      - POST
                    - type: 'null'
                  path:
                    type:
                    - string
                    - 'null'
                    pattern: ^\/v1\/[A-Za-z0-9/-]+$
                    maxLength: 200
                required:
                - event_id
                - platform
                - operation
                - status
                - duration_ms
                - timestamp
                - method
                - path
                additionalProperties: false
              maxItems: 100
            nextCursor:
              type:
              - string
              - 'null'
              maxLength: 2048
          required:
          - start
          - end
          - rows
          - nextCursor
          additionalProperties: false
      required:
      - success
      - status
      - requestId
      - coverage
      - data
      additionalProperties: false
    gatewayFailure:
      type: object
      required:
      - success
      - status
      - requestId
      - failure
      properties:
        success:
          const: false
        status:
          const: failed
        requestId:
          type: string
        failure:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
            message:
              type: string
  securitySchemes:
    amazon:
      type: apiKey
      in: header
      name: x-api-key
    bluesky:
      type: apiKey
      in: header
      name: x-api-key
    cosmos:
      type: apiKey
      in: header
      name: x-api-key
    couchsurfing:
      type: apiKey
      in: header
      name: x-api-key
    depop:
      type: apiKey
      in: header
      name: x-api-key
    dribbble:
      type: apiKey
      in: header
      name: x-api-key
    etsy:
      type: apiKey
      in: header
      name: x-api-key
    facebook-events:
      type: apiKey
      in: header
      name: x-api-key
    facebook-marketplace:
      type: apiKey
      in: header
      name: x-api-key
    facebook:
      type: apiKey
      in: header
      name: x-api-key
    github:
      type: apiKey
      in: header
      name: x-api-key
    hackernews:
      type: apiKey
      in: header
      name: x-api-key
    instagram:
      type: apiKey
      in: header
      name: x-api-key
    kalshi:
      type: apiKey
      in: header
      name: x-api-key
    kick:
      type: apiKey
      in: header
      name: x-api-key
    komi:
      type: apiKey
      in: header
      name: x-api-key
    kwai:
      type: apiKey
      in: header
      name: x-api-key
    linkbio:
      type: apiKey
      in: header
      name: x-api-key
    linkedin-ads:
      type: apiKey
      in: header
      name: x-api-key
    linkedin:
      type: apiKey
      in: header
      name: x-api-key
    linkme:
      type: apiKey
      in: header
      name: x-api-key
    linktree:
      type: apiKey
      in: header
      name: x-api-key
    mastodon:
      type: apiKey
      in: header
      name: x-api-key
    medium:
      type: apiKey
      in: header
      name: x-api-key
    meetup:
      type: apiKey
      in: header
      name: x-api-key
    meta-ads:
      type: apiKey
      in: header
      name: x-api-key
    pillar:
      type: apiKey
      in: header
      name: x-api-key
    pinterest:
      type: apiKey
      in: header
      name: x-api-key
    polymarket:
      type: apiKey
      in: header
      name: x-api-key
    producthunt:
      type: apiKey
      in: header
      name: x-api-key
    quora:
      type: apiKey
      in: header
      name: x-api-key
    reddit:
      type: apiKey
      in: header
      name: x-api-key
    rumble:
      type: apiKey
      in: header
      name: x-api-key
    skool:
      type: apiKey
      in: header
      name: x-api-key
    snapchat:
      type: apiKey
      in: header
      name: x-api-key
    substack:
      type: apiKey
      in: header
      name: x-api-key
    telegram:
      type: apiKey
      in: header
      name: x-api-key
    threads:
      type: apiKey
      in: header
      name: x-api-key
    tiktok-shop:
      type: apiKey
      in: header
      name: x-api-key
    tiktok:
      type: apiKey
      in: header
      name: x-api-key
    truthsocial:
      type: apiKey
      in: header
      name: x-api-key
    tumblr:
      type: apiKey
      in: header
      name: x-api-key
    twitch:
      type: apiKey
      in: header
      name: x-api-key
    twitter:
      type: apiKey
      in: header
      name: x-api-key
    usage:
      type: apiKey
      in: header
      name: x-api-key
    vinted:
      type: apiKey
      in: header
      name: x-api-key
    whatnot:
      type: apiKey
      in: header
      name: x-api-key
    youtube:
      type: apiKey
      in: header
      name: x-api-key
    dashboardSession:
      type: http
      scheme: bearer
      description: ScrapeAtlas dashboard session