YouScan History API
Manage historical data collection for a topic. Starting a collection can return `400` if a collection is already running, if the date range is invalid, or if the requested depth exceeds your plan's history limit.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/youscan-history-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: YouScan History API
version: '1.0'
contact:
name: YouScan Support
url: https://youscan.io
license:
name: Proprietary
url: https://youscan.io/terms-of-service
description: 'YouScan provides a REST API to manage topics, retrieve mentions, and query statistics
collected by the YouScan social media listening platform.'
servers:
- url: https://api.youscan.io/api/external
security:
- ApiKeyHeader: []
- ApiKeyQuery: []
tags:
- name: History
description: 'Manage historical data collection for a topic.
Starting a collection can return `400` if a collection is already running, if the date
range is invalid, or if the requested depth exceeds your plan''s history limit.'
paths:
/topics/{topicId}/history:
get:
tags:
- History
operationId: getHistoryDetails
summary: History collection details
description: Get the status and progress of the historical data collection job for the topic.
parameters:
- $ref: '#/components/parameters/TopicId'
responses:
'200':
description: History collection job details.
content:
application/json:
schema:
$ref: '#/components/schemas/HistoryJobDetails'
'204':
description: No history collection job exists for the topic.
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/TopicNotFound'
'401':
$ref: '#/components/responses/Unauthorized'
post:
tags:
- History
operationId: collectHistory
summary: Start history collection
description: Start collecting historical mentions for the topic for the given date range.
parameters:
- $ref: '#/components/parameters/TopicId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- from
- to
properties:
from:
type: string
format: date
description: ISO formatted date from.
to:
type: string
format: date
description: ISO formatted date to.
example:
from: '2025-01-01'
to: '2025-02-01'
responses:
'200':
description: History collection started.
'400':
$ref: '#/components/responses/ValidationError'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/TopicNotFound'
'401':
$ref: '#/components/responses/Unauthorized'
/topics/{topicId}/history/stop:
post:
tags:
- History
operationId: stopHistoryCollection
summary: Stop history collection
description: Stop the running historical data collection job.
parameters:
- $ref: '#/components/parameters/TopicId'
responses:
'200':
description: History collection stopped.
'400':
description: No active history collection job to stop.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Can't find collecting job for the topic
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/TopicNotFound'
'401':
$ref: '#/components/responses/Unauthorized'
components:
parameters:
TopicId:
name: topicId
in: path
required: true
description: ID of the Topic.
schema:
type: integer
responses:
Unauthorized:
description: The API key is missing or invalid.
ValidationError:
description: The request is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'
example:
errorCode: VALIDATION_ERROR
message: '''TextQuery'' should not be empty.'
errors:
- field: TextQuery
errorCode: notempty_error
message: '''TextQuery'' should not be empty.'
TopicNotFound:
description: Topic not found or you don't have access to it.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: Theme not found
Forbidden:
description: Your permission level for this topic is too low for the action.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
message: THEME_PERMISSION_DENIED
schemas:
ValidationError:
type: object
properties:
errorCode:
type: string
const: VALIDATION_ERROR
message:
type: string
errors:
type: array
items:
type: object
properties:
field:
type: string
errorCode:
type: string
message:
type: string
Error:
type: object
properties:
errorCode:
type: string
description: Machine-readable error code.
message:
type: string
description: Human-readable error description.
resourceType:
type: string
description: 'Present on `RESOURCE_NOT_FOUND` errors — the type of the missing resource (e.g. "Import", "Space").
'
HistoryJobDetails:
type: object
properties:
topicId:
type: integer
description: Topic ID.
status:
type: string
enum:
- collecting
- failed
- failedComplexQuery
- completed
- aborted
description: Job status.
started:
type:
- string
- 'null'
format: date-time
description: Date and time when the job started.
ended:
type:
- string
- 'null'
format: date-time
description: Date and time when the job finished.
from:
type: string
format: date-time
description: Date from which data is collected.
to:
type: string
format: date-time
description: Date until which data is collected.
query:
type: string
description: Search query used for historical data collection.
processedTo:
type:
- string
- 'null'
format: date-time
description: Date until which data is already collected.
progress:
type: integer
minimum: 0
maximum: 100
description: Percentage completed.
collected:
type: integer
description: Number of mentions processed.
saved:
type: integer
description: Number of mentions saved to the topic.
duplicates:
type: integer
description: Number of duplicate mentions skipped.
skipped:
type: integer
description: Number of mentions skipped.
invalid:
type: integer
description: Number of invalid mentions.
lastError:
type:
- string
- 'null'
description: Last error message, if the job failed.
example:
topicId: 123
status: collecting
started: '2021-02-01T13:01:00Z'
from: '2021-01-01T00:00:00Z'
to: '2021-02-01T00:00:00Z'
query: Tesla or SpaceX
processedTo: '2021-01-15T00:00:00Z'
progress: 15
collected: 1024
saved: 900
duplicates: 100
skipped: 20
invalid: 4
securitySchemes:
ApiKeyHeader:
type: apiKey
in: header
name: X-API-KEY
description: API key authentication. The recommended way to authenticate requests.
ApiKeyQuery:
type: apiKey
in: query
name: apiKey
description: API key as a query parameter. For testing purposes only.