backlinks_timeseries_new_lost_summary
Analyze new and lost backlinks and referring domains for a domain over a specified time period, with results grouped by day, week, month, or year for time-series visualization.
Instructions
This endpoint will provide you with the number of new and lost backlinks and referring domains for the domain specified in the target field. The results will be provided for a period between the two indicated dates, and metrics will be grouped by the time range that you define: day, week, month, or year. Data from this endpoint will be especially helpful for building time-series graphs of new and lost backlinks and referring domains.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| target | Yes | domain to get data for required field a domain should be specified without https:// and www. example: "forbes.com" | |
| date_from | No | starting date of the time range optional field this field indicates the date which will be used as a threshold for summary data; minimum value: 2019-01-30 maximum value shouldn’t exceed the date specified in the date_to date format: "yyyy-mm-dd" example: "2021-01-01" | |
| date_to | No | ending date of the time range optional field if you don’t specify this field, the today’s date will be used by default minimum value shouldn’t preceed the date specified in the date_from maximum value: today’s date date format: "yyyy-mm-dd" example: "2021-01-15" | |
| group_range | No | time range which will be used to group the results optional field default value: month possible values: day, week, month, year note: for day, we will return items corresponding to all dates between and including date_from and date_to; for week/month/year, we will return items corresponding to full weeks/months/years, where each item will indicate the last day of the week/month/year for example, if you specify: "group_range": "month", "date_from": "2022-03-23", "date_to": "2022-05-13" we will return items falling between 2022-03-01 and 2022-05-31, namely, three items corresponding to the following dates: 2022-03-31, 2022-04-30, 2022-05-31 if there is no data for a certain day/week/month/year, we will return 0 | month |
Implementation Reference
- The `handle` method that executes the tool's core logic: sends a POST request to the DataForSEO `/v3/backlinks/timeseries_new_lost_summary/live` endpoint with the provided parameters and handles the response or error.async handle(params: any): Promise<any> { try { const response = await this.client.makeRequest('/v3/backlinks/timeseries_new_lost_summary/live', 'POST', [{ target: params.target, date_from: params.date_from, date_to: params.date_to, group_range: params.group_range }]); return this.validateAndFormatResponse(response); } catch (error) { return this.formatErrorResponse(error); } }
- The `getParams` method defines the input schema using Zod, including required `target` domain, optional `date_from`, `date_to`, and `group_range` (default 'month') with detailed descriptions.getParams(): z.ZodRawShape { return { target: z.string().describe(`domain to get data for required field a domain should be specified without https:// and www. example: "forbes.com"`), date_from: z.string().describe(`starting date of the time range optional field this field indicates the date which will be used as a threshold for summary data; minimum value: 2019-01-30 maximum value shouldn’t exceed the date specified in the date_to date format: "yyyy-mm-dd" example: "2021-01-01"`).optional(), date_to: z.string().describe(`ending date of the time range optional field if you don’t specify this field, the today’s date will be used by default minimum value shouldn’t preceed the date specified in the date_from maximum value: today’s date date format: "yyyy-mm-dd" example: "2021-01-15"`).optional(), group_range: z.string().optional().describe(`time range which will be used to group the results optional field default value: month possible values: day, week, month, year note: for day, we will return items corresponding to all dates between and including date_from and date_to; for week/month/year, we will return items corresponding to full weeks/months/years, where each item will indicate the last day of the week/month/year for example, if you specify: "group_range": "month", "date_from": "2022-03-23", "date_to": "2022-05-13" we will return items falling between 2022-03-01 and 2022-05-31, namely, three items corresponding to the following dates: 2022-03-31, 2022-04-30, 2022-05-31 if there is no data for a certain day/week/month/year, we will return 0`).default('month') }; }
- src/core/modules/backlinks/backlinks-api.module.ts:47-47 (registration)Instantiation of the `BacklinksTimeseriesNewLostSummaryTool` instance, which is added to the list of tools in `BacklinksApiModule`'s `getTools()` method. This tool is then registered with its name, description, params schema, and handler wrapper.new BacklinksTimeseriesNewLostSummaryTool(this.dataForSEOClient),
- src/core/modules/backlinks/backlinks-api.module.ts:54-61 (registration)The `reduce` operation in `getTools()` that registers all tools, including this one, by mapping tool names to their descriptions, params schemas, and handler functions.return tools.reduce((acc, tool) => ({ ...acc, [tool.getName()]: { description: tool.getDescription(), params: tool.getParams(), handler: (params: any) => tool.handle(params), }, }), {});